Integration overview
Authorization flow
- Your application creates a short-lived OAuth transaction containing random
state, a PKCE verifier, the exact callback URI, and optionally an OIDC nonce. - The browser navigates to Sigma's authorization endpoint with the S256 challenge and requested scopes.
- Sigma authenticates the user, asks them to select an identity when necessary, and obtains consent.
- Sigma redirects to your registered callback with
code,state, and issuer information. - Your server verifies the transaction belongs to this browser, checks expiry and issuer, consumes it once, and exchanges the code using its registered member signing key.
- Your app establishes its own session and checks that session before returning protected data.
The authorization page checks a Better Auth session, not a client-side “backup unlocked” cookie. Unlocking is needed for local key operations, not every OAuth redirect.
Package entry points
| Import | Role |
|---|---|
@sigma-auth/better-auth-plugin/client | sigmaClient() and browser signer clients |
@sigma-auth/better-auth-plugin/server | exchangeCodeForTokens() and sigmaCallbackPlugin() |
@sigma-auth/better-auth-plugin/next | Next.js callback adapters |
@sigma-auth/better-auth-plugin/provider | sigmaProvider() for operating a Sigma issuer |
Installing sigmaProvider() in a relying-party app does not configure “Sign in with Sigma.” Follow Next.js or JavaScript instead.
Credentials and sessions
The application member key authenticates the OAuth client. User identity keys sign in as a person. PKCE binds a code to the initiating transaction. These are different controls; one does not replace the others.
The current issuer requires X-Auth-Token Bitcoin signatures for authorization-code and refresh exchanges. A browser-only SPA cannot safely hold that application key; give it a backend. Generic OAuth discovery describes Better Auth capabilities but does not express this extra hook.
createCallbackHandler() returns tokens and user data only. createBetterAuthCallbackHandler({ auth }) also creates a local Better Auth session. Neither Next callback helper independently validates OAuth state; add the transaction validation described in Next.js.
Claims and resource access
Request openid for an ID token, profile for public profile claims, email for the verified account email when available, and offline_access when refresh access is needed. bap_id is distinct from sub; the bap claim may be a JSON string. See tokens.
An OAuth access token is not automatically accepted by every Sigma account endpoint. Consult each route's authentication column in the API reference.