# Use OhAuthCat SSO with Supabase

Use this guide when your application uses Supabase Auth. After your callback obtains the verified OhAuthCat profile, the Supabase helper finds or creates the user through the admin API and starts a session by generating a magic link with the service role and verifying it on the server.

## Identity-linking rule

The helper keys the user by the profile's `connection_id` and `idp_id`: the link key is `oac_` followed by the first 40 hex characters of SHA-256 over `connection_id`, a newline and `idp_id`. Email is never used to match. You choose the policy on every call: `refuse` signs in only users that are already linked, `create` also creates the missing user. When the provider already holds an unlinked account with the same email, the helper fails with `email_conflict`; link that account through a signed-in, explicit flow instead of merging on email.

## Set up Supabase

1. Use the project URL and the service role key on the server only. Never send the service role key to the browser.
2. The helper creates users with an ID derived from the link key (a UUID), stores the link under `app_metadata.ohauthcat` and confirms the email only when the profile reports it verified.
3. Return the session's access and refresh tokens to the browser and call `supabase.auth.setSession(...)`, or use the magic-link URL instead if you prefer a redirect.

## Node

```javascript
const supabase = new SupabaseLinker({
  url: process.env.SUPABASE_URL ?? "https://example.supabase.co",
  serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY ?? "placeholder",
});

export async function linkUser(profile) {
  const { user } = await linkIdentity(profile, supabase, {
    onMissing: "create",
  });
  return supabase.startSession(user);
}

export async function revokeUser(userId) {
  await supabase.revoke(userId);
}
```

## Python

```python
import os

from ohauthcat.existing_auth import LinkPolicy, SupabaseLinker, link_identity

supabase = SupabaseLinker(
    url=os.environ.get("SUPABASE_URL", "https://example.supabase.co"),
    service_role_key=os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "placeholder"),
)


def link_user(profile):
    user = link_identity(profile, supabase, LinkPolicy("create")).user
    return supabase.start_session(user)


def revoke_user(user_id):
    supabase.revoke(user_id)
```

## Go

```go
package main

import (
	"context"
	"os"

	ohauthcat "ohauthcat.com/sdk-go"
	"ohauthcat.com/sdk-go/existingauth"
)

func linkUser(ctx context.Context, profile ohauthcat.Profile) (existingauth.SupabaseSession, error) {
	l, err := existingauth.NewSupabaseLinker(existingauth.SupabaseOptions{
		URL:            os.Getenv("SUPABASE_URL"),
		ServiceRoleKey: os.Getenv("SUPABASE_SERVICE_ROLE_KEY"),
	})
	if err != nil {
		return existingauth.SupabaseSession{}, err
	}
	res, err := existingauth.Link(ctx, existingauth.FromProfile(profile), l,
		existingauth.Policy{OnMissing: existingauth.OnMissingCreate})
	if err != nil {
		return existingauth.SupabaseSession{}, err
	}
	return l.StartSession(ctx, res.User)
}
```

## Revoke sessions on `dsync.user.deleted`

Call `revoke` with the Supabase user ID. It bans the user, so refresh tokens can no longer be exchanged; access tokens already issued remain valid until they expire. A user that no longer exists is treated as already revoked.

Verify the webhook first ([webhook verification](/events/webhook-verification/)), then map the directory user to your linked user through your own organization-scoped record. OhAuthCat does not close sessions in your provider for you.

## Troubleshooting

| Code                   | Meaning                                                                           |
| ---------------------- | --------------------------------------------------------------------------------- |
| `invalid_input`        | A profile field or option is missing or malformed                                 |
| `not_linked`           | No linked user and the policy is `refuse`                                         |
| `email_conflict`       | An unlinked account already uses this email or identifier                         |
| `provider_error`       | The provider refused the call (HTTP status in `status`)                           |
| `provider_unavailable` | Network failure, timeout, HTTP 429 or 5xx                                         |
| `invalid_response`     | The provider answered with an unexpected body                                     |
| `session_refused`      | The provider would not start a session (disabled, banned, wrong challenge answer) |

Error messages never contain tokens, secrets or provider response bodies, so they are safe to log.

- `email_conflict` with `email_exists`: a Supabase user already has this email without the link.
- `invalid_input` on create: Supabase users created by the helper need an email.
- `session_refused`: the user is banned, or the magic link expired before verification.

See also [working with existing auth](/sso/working-with-existing-auth/) and [profiles](/sso/profiles/).
