Client plugin reference
import { createAuthClient } from "better-auth/client";
import { sigmaClient } from "@sigma-auth/better-auth-plugin/client";
export const authClient = createAuthClient({ plugins: [sigmaClient()] });Configure NEXT_PUBLIC_SIGMA_AUTH_URL and NEXT_PUBLIC_SIGMA_CLIENT_ID in the app. The Better Auth client's base URL identifies your app's session handler; the Sigma issuer is configured separately.
Redirect sign-in
await authClient.signIn.sigma({
clientId: "your-registered-client-id",
callbackURL: "/auth/sigma/callback",
errorCallbackURL: "/auth/sigma/error",
scope: "openid profile email",
});Options include prompt, bapId, and forceLogin. A requested bapId is an identity-selection hint, not proof of ownership. Direct authToken sign-in is a different issuer-side flow; do not pass an application WIF into the browser API.
The client generates PKCE, stores the verifier/state/redirect URI in sessionStorage, and navigates to Sigma. On callback, authClient.sigma.handleCallback(searchParams) checks saved state and invokes the local /api/auth/sigma/callback route for cross-domain exchange. It returns user data and tokens. Call it once per transaction; do not parse a callback in multiple components.
Server requirements
The local callback route must validate a server-owned, browser-bound OAuth transaction before accepting the code. Client-side sessionStorage validation is not sufficient protection for a directly callable HTTP endpoint. For a new integration, prefer the server-owned flow, which does not need handleCallback().
| Server helper | Result |
|---|---|
exchangeCodeForTokens() from /server | Token exchange and userinfo; no local session |
createCallbackHandler() from /next | POST adapter returning tokens/user; no local session |
createBetterAuthCallbackHandler({ auth }) from /next | Token exchange, local user/account update, and local Better Auth session cookie |
sigmaCallbackPlugin() from /server | Better Auth callback endpoint for non-Next compositions; inspect the installed version's options |
The Next adapters accept issuerUrl, clientId, accountPrivateKey, and callbackPath. createBetterAuthCallbackHandler additionally accepts account lookup/creation/update policy hooks and disableImplicitSignUp. See Next.js before exposing a callback route.
Signing clients
SigmaCWISigner, SigmaIframeSigner, and LocalServerSigner are separate signing transports. Use the signing guide for initialization, identity selection, cleanup, and permission boundaries.
Version compatibility
Check the installed package's exports, TypeScript declarations, and Better Auth peer dependency together. Provider, client, and callback packages evolve independently of the hosted server deployment. Do not infer a supported method from an old example or install the issuer sigmaProvider() plugin merely to consume Sigma sign-in.