Add “Are you an agent?”

Versine connects to your existing Auth0 tenant or Supabase project as an OpenID Connect (OIDC) provider. Agents sign in through it like any other user. Your app keeps control of accounts, sessions and permissions. Agents connected to Versine sign in as their person. Agents without Versine get a claimable account: a restricted account their person claims within 24 hours. Both use the same button.

Versine supports Auth0 and Supabase.

1. Register the project

Auth0
Supabase

Auth0 domain: your tenant or custom domain, such as https://example.us.auth0.com.
Connection name: such as versine. You’ll use the same name in Auth0.
Callback URL: that domain followed by /login/callback, exactly.

Supabase project URL: the Project URL in Project Settings → Data API, without any path such as /rest/v1/: for example https://abcdefgh.supabase.co. If you use a custom domain (Project Settings → Custom Domains), use that instead.
Provider identifier: a name you choose, of lowercase letters, numbers and hyphens, such as versine. Supabase calls the provider custom:versine.
Callback URL: that URL followed by /auth/v1/callback, exactly. Supabase also shows it as the Callback URL when you add the provider under Authentication → Sign In / Providers.

Webhook URL: an HTTPS endpoint on your server. See step 6.
Lifecycle webhook URL: for claimable account events. It can be the same endpoint.

Continuing past Integration saves a draft and creates your credentials. Drafts can’t sign anyone in; choose Finish setup after steps 2–6.

VERSINE_CLIENT_ID=...
VERSINE_CLIENT_SECRET=...    # your auth provider and server; never the browser
VERSINE_WEBHOOK_SECRET=...   # your server, for verifying webhooks

Set up with a coding agent

Choose Use my AI assistant when creating the project. Console copies a prompt with the full integration guide and your project’s non-secret settings. Paste it into your coding agent with your repository open. Enter secrets into your auth provider and secret manager yourself.

Under Advanced, optionally add your Terms of Service and Privacy Policy URLs. People accept them in My before their first sign-in, when claiming an account, and again whenever you change a URL. Agents can’t accept for them. Leave both empty to skip this.

2. Connect your auth provider

Auth0
Supabase

In Auth0, open Authentication → Enterprise → OpenID Connect and create a connection:

Name: the connection name from step 1.
Discovery URL: https://auth.versine.com/.well-known/openid-configuration.
Client ID and secret: from your Versine project, not your Auth0 application.
Type: Back Channel, with client_secret_basic authentication.
Scopes: openid profile email.
PKCE: S256.

Confirm the callback Auth0 shows matches the one in your project. Then enable the connection for your application on the Applications tab.

Security profiles

Keep S256 PKCE, the default, unless Auth0 can’t use it on this connection. Choose Nonce only if Auth0 sends and validates a fresh nonce and state to Versine instead. PKCE between your app and Auth0 does not protect the separate connection from Auth0 to Versine.

Add Versine as a custom OIDC provider. From your server, with your service-role key:

await supabase.auth.admin.customProviders.createProvider({
  provider_type: "oidc",
  identifier: "custom:versine", // your provider identifier from step 1
  name: "Versine",
  issuer: "https://auth.versine.com",
  client_id: process.env.VERSINE_CLIENT_ID,
  client_secret: process.env.VERSINE_CLIENT_SECRET,
  scopes: ["openid", "profile", "email"],
  pkce_enabled: true,
  email_optional: true, // unclaimed accounts have no email
  custom_claims_allowlist: [
    "https://versine.com/claims/provider",
    "https://versine.com/claims/account_state",
    "https://versine.com/claims/claim_expires_at",
    "https://versine.com/claims/trust_level",
    "https://versine.com/claims/permissions",
  ],
});

You can also create it in the Supabase dashboard; check that PKCE, email_optional and the claims allowlist match. Confirm the callback Supabase shows matches the one in your project. Supabase always uses S256 PKCE, so Versine projects for Supabase use the PKCE profile.

Add Are you an agent? to both your login and sign-up pages. Keep your existing sign-in options.

Auth0
Supabase

Point the button at Auth0’s login with your Versine connection:

import { useAuth0 } from "@auth0/auth0-react";

const { loginWithRedirect } = useAuth0();

<button
  onClick={() =>
    loginWithRedirect({ authorizationParams: { connection: "versine" } })
  }
>
  Are you an agent?
</button>;

With a server-side SDK, pass connection=versine to its login route. Let the SDK handle state, nonce and PKCE.

Start Supabase’s OAuth sign-in with your Versine provider, returning to a callback route on your server:

<button
  onClick={() =>
    supabase.auth.signInWithOAuth({
      provider: "custom:versine",
      options: { redirectTo: `${location.origin}/auth/callback` },
    })
  }
>
  Are you an agent?
</button>

Use Supabase’s server-side (PKCE) flow so your server exchanges the code in step 4.

4. Connect user accounts

Auth0
Supabase

Identify users by Auth0’s verified user ID, such as oidc|versine|<subject>. Use email and name for profile information, not as account identifiers. Versine emails can be unverified (email_verified: false), so never link accounts by email.

Identify users by their Supabase user ID. The Versine subject is the identity’s provider_id in auth.identities, for provider custom:versine.Supabase automatically links a sign-in to an existing user with the same verified email, and this can’t be turned off. Versine marks an email verified only after the person proves it, and never for unclaimed accounts. A Versine sign-in can therefore reach the person’s existing account, so keep agent restrictions on the session, not the user. See identity linking.

Identify agent sign-ins

Versine adds https://versine.com/claims/provider: "versine" to its profile. Neither provider forwards it into your app’s tokens.

Auth0
Supabase

Set it in a post-login Action keyed to the Versine connection:

exports.onExecutePostLogin = async (event, api) => {
  if (event.connection.id !== "con_...") return; // your Versine connection ID
  const claim = "https://versine.com/claims/provider";
  api.idToken.setCustomClaim(claim, "versine");
  api.accessToken.setCustomClaim(claim, "versine");
};

Supabase’s session doesn’t record which provider signed in, and user_metadata can be edited by the user. In your callback, exchange the code, then ask Versine who signed in using the session’s provider_token:

const { data } = await supabase.auth.exchangeCodeForSession(code);
const res = await fetch("https://auth.versine.com/userinfo", {
  headers: { Authorization: `Bearer ${data.session.provider_token}` },
});
// 200: this sign-in came through Versine. Any other provider's token fails.
const versine = res.ok ? await res.json() : null;

Save the result on your server against the session’s session_id claim. Don’t store the provider_token; it expires in five minutes.

Treat this as where the sign-in came from, not as a role or permission.

Decide what agents can do

Agree which reads, writes and resources agents may use, and which actions need a person, such as billing, admin and deletion. Enforce it on your backend:

Allow the user’s own rights, limited to your agent allowlist.
Keep the sign-in source in your server session, not in client parameters.
Treat a missing source as an agent, not a person.
Keep restrictions through refresh, silent sign-in and account linking.

Link accounts

Account linking lets a user return through another provider to the same account. With Auth0, require the user to sign in to both accounts and consent. Never link by email alone. See Auth0 account linking. Supabase links verified emails automatically; don’t add your own email-based linking on top.

5. Limit claimable accounts

An agent without Versine signs up with a claimable account. Its email can’t receive mail, and it expires after 24 hours unless its person claims it. In Console, choose the Unclaimed product permissions these accounts get, such as projects:read. The default is none. After each Versine sign-in, look up the account state from your server:

curl https://api.versine.com/api/claimable/resolve \
  -u "$VERSINE_CLIENT_ID:$VERSINE_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"platformSubject": "<subject>"}'

404: a regular Versine user. Continue as in step 4.
accountState: "unclaimed": allow only your unclaimed permissions, until claimExpiresAt.
Don’t require email verification for unclaimed accounts.
With Supabase, keep email out of Unclaimed OIDC scopes (Console does this for you). Supabase refuses sign-ins with an unverified email when email confirmation is on.
Save the state in the session. Full access starts with a fresh sign-in after the claim.

See Claimable accounts for the full flow and what to allow.

6. Receive webhooks

Versine sends authorization.completed to your webhook URL after each sign-in, and claimable account events to your lifecycle webhook URL. Webhooks notify your server; they don’t sign anyone in.

Verify X-Versine-Signature against the raw body with VERSINE_WEBHOOK_SECRET.
Store the event ID with a unique constraint and ignore duplicates.
Return exactly 200. Any other status is retried.
On claimable.claimed, update the email and end restricted sessions. On claimable.expired, disable the account.

See Webhooks for payloads and a verification example.

Connect an agent using the agent setup guide. Ask it to sign in to your app and confirm it reaches a protected page.
Try a new user: confirm an account is created. Sign in again and confirm the same account is used.
Ask an agent without Versine to sign up. Confirm it gets only your unclaimed permissions.
Claim that account from its claim link. Confirm you receive claimable.claimed and the next sign-in reaches the same account with full access.
Confirm your server responds 200 to each webhook.
Sign out and confirm access is denied.

Check these first:

invalid_redirect_uri: match the project’s callback to your provider’s exactly, with no query.
invalid_client: use your Versine project’s client ID and secret in your provider, with client_secret_basic.
invalid_request: check S256 PKCE, or state and nonce for the nonce profile.
The agent is approved but the browser stays signed out: restart from your app’s sign-in button. Approval alone doesn’t create your app’s session.
A webhook is marked failed after 204: only 200 counts as delivered.
Supabase returns provider_email_needs_verification: remove email from the project’s unclaimed scopes and set email_optional on the Supabase provider.

Get started

For platforms

For people and agents

Add “Are you an agent?”

1. Register the project

2. Connect your auth provider

4. Connect user accounts

5. Limit claimable accounts

6. Receive webhooks

​1. Register the project

​2. Connect your auth provider

​3. Add the sign-in button

​4. Connect user accounts

​5. Limit claimable accounts

​6. Receive webhooks

​7. Test sign-in

1. Register the project

2. Connect your auth provider

3. Add the sign-in button

4. Connect user accounts

5. Limit claimable accounts

6. Receive webhooks

7. Test sign-in