Heimdall docs
Guides
Build with Heimdall.
Nine 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 Heimdall, 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 Heimdall-admin), per-app JWKS, identity primitives, when to reach for each.
Read more 02 · Quickstart — add Heimdall to your product
Provision an app, configure auth, ship signup + signin + /me. The minimum surface a customer-facing product needs.
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 Heimdall 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
PAK-only mint endpoints, customer-side delivery via your own SMTP, the Envoi-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 Heimdall app. Native iOS / macOS, web redirect flow, encrypted-at-rest provider config, account linking by verified email.
Read more Conventions
What to expect
- Working code in every chapter. Snippets are
curl+ JavaScript fetch — copy-paste-ready, not pseudocode. Substitute the obvious values (<your-app-slug>,<your-pak>) 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.”