Quickstart

1. Register your application

Sign in at Sigma Auth, select your identity, and open OAuth Clients in the account navigation. Register the exact callback URL, including scheme, hostname, port, and path. Register the public key corresponding to your application's server-held member signing key. See client registration.

A made-up client_id will not work. Dynamic Client Registration alone does not provision the accountPubkey required by Sigma's authorization-code token hook.

2. Install the integration package

bun add @sigma-auth/better-auth-plugin better-auth

Use compatible versions and commit your lockfile. The protocol audit used the auth server's @sigma-auth/better-auth-plugin@0.0.97; package APIs and deployment versions are separate facts.

3. Configure your application

NEXT_PUBLIC_APP_URL=https://your-app.example
NEXT_PUBLIC_SIGMA_AUTH_URL=https://auth.sigmaidentity.com
NEXT_PUBLIC_SIGMA_CLIENT_ID=your-registered-client-id
SIGMA_MEMBER_PRIVATE_KEY=your-server-only-member-wif

These are integration settings in your application, not auth-server deployment settings. Never prefix SIGMA_MEMBER_PRIVATE_KEY with NEXT_PUBLIC_, put it in browser code, or reuse a user's master key as an application credential.

4. Implement the flow

Use the Next.js guide for the Better Auth callback adapter, or the JavaScript guide for the server-side protocol steps. The React guide covers the client UI.

Every flow needs a fresh S256 PKCE verifier, a browser-bound state transaction, an exact registered redirect URI, and server-side client authentication. Validate the callback before exchanging its code. Store the resulting application session in an HttpOnly cookie and enforce access on the server.

5. Verify locally before release

Use a staging client with a registered local callback. Check successful sign-in, rejected consent, wrong/missing state, wrong PKCE verifier, an expired code, repeated callback delivery, and sign-out. Confirm protected endpoints reject a request without your application session. Inspect network requests to confirm the member WIF and user backup secrets never enter the browser request payload.

See troubleshooting for redirect, signature, and session failures.