Auth docs
Guides
Build with Auth.
Fourteen chapters covering everything from your first authenticated request to multi-tenant role catalogues maintained from CI. Each chapter is self-contained; jump in where the work is.
The chapters build on each other but you don't need to read in order. If you've already shipped signup + signin and you want to add roles, jump straight to 03 · Roles + permissions. If you're wiring a backend cron to call Auth, jump to 05 · M2M or 06 · Verify tokens.
Looking for the full HTTP API instead of a guided tour? See API reference. Looking for the conceptual model — apps, tenants, the two lanes — see Core concepts.
Chapters
The series
01 · Foundations
Apps, the two API surfaces (Consumer vs Auth-admin), per-app JWKS, identity primitives, when to reach for each.
Read more 02 · Quickstart — add Auth to your product
Create an app, turn on sign-up, sign a user up and in, read /me, verify the token. Node SDK and curl.
Read more 03 · Roles + permissions
Per-app RBAC catalogue, system roles, custom roles, granting permissions, caller-narrowing, the Consumer-API admin lane.
Read more 04 · Multi-tenancy with tenants
When to model your customers’ multi-tenancy as Auth tenants, the org_id JWT claim, member roles inside a tenant, switching tenants.
Read more 05 · M2M for backend services
Issue M2M credentials, exchange for tokens via client_credentials, scope narrowing, last_used_at, secret rotation.
Read more 06 · Verify tokens in your service
Three verification shapes: local JWKS verification, /oauth/introspect for opaque introspection, /verify + /authorize for one-call permission checks.
Read more 07 · Email verification + password reset
API-key-only mint endpoints, customer-side delivery via your own SMTP, the Mail-integrated shortcut, the consume side.
Read more 08 · Webhooks + audit
Subscribe to user lifecycle events with signed payloads, retry policy, secret rotation. Read the per-app audit log for compliance + debugging.
Read more 09 · Sign in with Apple
Add federated sign-in to any Auth app. Native iOS / macOS, web redirect flow, encrypted-at-rest provider config, account linking by verified email.
Read more 10 · Passkeys
Turn on WebAuthn per app, pick a relying-party id you can live with, and ship both flows: a passkey as a second factor, and passwordless sign-in with no password at all.
Read more 11 · Migrating users from another provider
Bulk-import your existing users as NDJSON — with their argon2id or bcrypt password hashes, so nobody resets a password — read the per-row error report, watch the credentials upgrade to argon2id on first signin, and export everything back out.
Read more 12 · Sign in with Google
Create a Web application OAuth client in Google Cloud, paste the redirect URI the console shows, save (Auth checks the credentials with Google), Try sign-in, add the button.
Read more 13 · Sign in with GitHub
Register a GitHub OAuth app with the callback URL the console shows, save the Client ID and secret (checked with GitHub on save), Try sign-in, add the button.
Read more 14 · Let your customers create API keys
Tenant API keys for your customers’ CI and e2e tests: push the key settings on boot, verify keys with a cache and single-flight, fail closed, proxy key management through your backend, accept keys only on the routes you mark.
Read more Conventions
What to expect
- Working code in every chapter. Snippets are
curl+ the@productcraft/authSDK — copy-paste-ready, not pseudocode. Substitute the obvious values (<your-app-slug>,<your-api-key>) and the calls work. - Production-ready, not just minimal. Each chapter calls out the security model, the error paths you care about (409 conflict, 403 policy-deny, 410 expired), and the defaults you should leave alone vs override.
- Cross-references back to the API reference.Every endpoint mentioned in a guide links to its full definition. Treat guides as the “how do I” and the reference as the “what does this return.”