Auth0 integration

Connection settings

Create an Enterprise → OpenID Connect connection in your Auth0 tenant. Use the same connection name and exact /login/callback origin registered in Console, including any Auth0 custom domain.

Enable the connection for your Auth0 application. Auth0 can discover PKCE support; our live test explicitly sets options.connection_settings.pkce to S256. The tested API accepted uppercase S256; provider documentation may show different casing, so verify your saved connection rather than disabling PKCE.

Only select Versine's confidential nonce profile when you have verified Auth0 sends and validates a fresh upstream nonce plus state. Chroma does not support the legacy confidential_code profile. Auth0's connection documentation

Start the flow

Use your Auth0 SDK's login operation with connection: "your-connection-name" as an authorization parameter. Label that entry Are you an agent? on both login and signup screens. Keep the existing human entry points. The SDK must complete your application callback and verify Auth0's resulting session. Upstream and downstream PKCE/state/nonce checks protect different legs.

Standard identity

Request name/email scopes. Auth0 maps profile attributes according to its connection settings. At the platform, use your verified Auth0 identity and tenant as the account key; do not merge accounts merely because emails match.

Identify Versine downstream

Versine emits https://versine.com/claims/provider: "versine" in its profile. OIDC does not require brokers to forward custom claims. Auth0 attribute mapping and downstream token claims are separate steps.

If storing upstream attributes, explicitly map only the profile fields your app needs; do not use unrestricted bind_all. Do not overwrite downstream iss with Versine's issuer. See Auth0's mapping guide.

For a provider indicator on the current login, a post-login Action can derive it from the trusted, fixed Versine connection ID. This avoids trusting an old linked user profile or a client-supplied parameter:

type LoginEvent = {
  connection?: { id?: string };
  client: { client_id: string };
};
type LoginApi = {
  idToken: { setCustomClaim(name: string, value: string): void };
  accessToken: { setCustomClaim(name: string, value: string): void };
};

export function onExecutePostLogin(event: LoginEvent, api: LoginApi) {
  // Non-secret, deployment-specific allowlist. Replace before deployment.
  const expected = "SET_TO_YOUR_VERSINE_CONNECTION_ID";
  const application = "SET_TO_YOUR_AUTH0_APPLICATION_CLIENT_ID";
  if (
    event.client.client_id === application &&
    event.connection?.id === expected
  ) {
    const claim = "https://versine.com/claims/provider";
    api.idToken.setCustomClaim(claim, "versine");
    api.accessToken.setCustomClaim(claim, "versine");
  }
}

This is a TypeScript source example. Compile it for Auth0's supported Action runtime and expose onExecutePostLogin in its CommonJS entry; Auth0's editor does not run TypeScript directly. Set the fixed connection and application IDs, deploy, bind it to the Login flow, and test both Versine and non-Versine logins, including linked accounts. Do not treat this indicator as a role, permission or MFA proof. Action API reference

Request the platform API audience for a verifiable access token. The platform must validate Auth0's signature, issuer, audience and expiry before reading claims. ID tokens are for the login/session callback, not API bearer authentication.

Agent permissions

Agree on permitted reads/writes, tenant/resource boundaries, session lifetime and which destructive/billing/admin operations need fresh human confirmation. Enforce the intersection of user rights and the agent allowlist on every backend request. Keep current-login provenance in a server-owned session; don't derive it from client parameters or a linked identity on the profile. Missing/ambiguous provenance must not silently grant human privileges. Preserve restrictions across refresh, linking and silent SSO, and test both agent and verified human paths.

Account linking

We recommend linking identities so a user can later choose another linked provider and reach the same platform account. This does not happen automatically: obtain consent and authenticate both accounts, choose a primary identity deliberately, and keep your platform's account association stable. Never auto-link by email alone, even verified email. Linking must not upgrade an agent session's privileges. Auth0 account linking.

Local development

A hosted Auth0 tenant cannot reach your desktop's .localhost endpoints. Use the isolated live-test harness for a real exchange. Do not expose the development database or all internal routes to solve this.