Migration Guides
Migrating older integrations
This is a migration guide for older Sigma examples. “v2” in this URL is a documentation-era label, not a promise of a 2.x Sigma package or a database migration number. Check the installed package and deployed server revision before changing an integration.
Breaking assumptions to remove
| Older assumption | Current contract |
|---|---|
/sigma/authorize or /api/auth/token is the hosted OAuth endpoint | Discover /api/auth/oauth2/authorize and /api/auth/oauth2/token |
| Client secret alone authenticates a Sigma code exchange | Registered accountPubkey and Bitcoin X-Auth-Token, plus PKCE |
plain PKCE fallback | S256 only |
createCallbackHandler() signs the user into the local app | It returns tokens; use a session adapter after server-side transaction validation |
| Callback adapter validates state by itself | Your server must verify a browser-bound, unexpired, single-use transaction |
sigmaProvider({ sigmaAuthUrl }) consumes Sigma | /provider operates an issuer; use client/server/Next exports as a consumer |
| A local “unlocked backup” cookie gates OAuth authorization | Better Auth session gates the hosted authorize flow |
bap is always a full object with idKey | It may be JSON text; selected identity is bap_id |
/api/profile/create accepts a password | Keys stay local; profile registration/drafts use the documented profile APIs |
oauthId publicly retrieves ciphertext | An owned linked-account session is required |
| Backups use a ten-year KV-only record | PostgreSQL backup and recovery-link repositories with cache support |
| Any Bitcoin verification response is a session token | Use real OAuth/Better Auth sessions; the legacy helper's base64 JSON is not one |
Upgrade procedure
- Pin compatible Better Auth/Sigma versions and commit the lockfile.
- Register exact staging callback URIs and verify the application member public key.
- Replace callback code with a server-owned state/PKCE flow and explicit account-linking policy.
- Preserve existing user IDs, provider-account associations, BAP IDs, and backup formats. Do not generate replacement keys or silently migrate root derivation.
- Test old and new users, missing verified email, multiple profiles, refresh/revocation, invalid state, duplicate callbacks, backup restore, and sign-out.
- Roll out through the owning repository's staging/release process with a rollback plan.
A dependency upgrade does not authorize ad hoc database migrations or activation of gated seed/certificate features. Self-hosted operators must follow their migration ledger and the deployment requirements in their checked-out source.
See Next.js, tokens, Backup API, and Profile API.