The Heimdall mental model.

An app in Heimdall is the identity boundary for one of your products. If you run a SaaS called Acme, you create one Heimdall app called acme and every user of Acme — the people who sign up for Acme, sign in to Acme, hold roles inside Acme — lives inside that app.

Apps are owned by a workspace (your team). One workspace can own many apps — useful if you run several products, or if you want a separate acme-staging for non-prod environments. Apps are cryptographically isolated: each app has its own JWKS (JSON Web Key Set) for signing tokens, so a token signed for acme cannot authenticate against acme-staging.

What apps don't do: they don't talk to each other. Two apps in the same workspace share no identity, no roles, no permissions. If you want unified login across two of your products, that's one app with two clients — not two apps.

Heimdall serves two different HTTP surfaces. They look superficially similar (both speak JSON, both use Bearer auth) but they exist for different actors:

Which one do you hit? If you're building the product itself (your customer signs up here, signs in here), it's the Consumer API. If you're building ops tools (CI provisions a new app for staging; a Terraform module manages your role catalogue), it's Heimdall-admin.

A common mistake: trying to manage Heimdall apps from the Consumer API (it doesn't expose app CRUD) or trying to sign in an end-user via Heimdall-admin (it doesn't verify end-user tokens). Pick the surface that matches the actor.

Three identity primitives live in Heimdall:

• EndUser — a person who signed up for one of your apps. Lives in account with app_id set. Tokens carry a type: 'end_user' claim. EndUsers hit the Consumer API.
• M2M client — a service principal for backend-to-backend traffic. Lives in m2m_client. Authenticates via OAuth 2.0 client_credentials grant. Tokens carry a type: 'm2m' claim + a scopes[] array.
• PlatformUser — you, the workspace owner. Lives in platform_auth.account (different database). Signs in via auth.productcraft.co. Hits Heimdall-admin with a cookie.

Plus one credential type that's not a principal:

• PAK (Platform API Key) — pcft_live_*. A workspace-scoped credential minted by a PlatformUser. Used for Heimdall-admin from CI and for the Consumer API mint endpoints (request-verification, request-password-reset).

When you create an app, Heimdall provisions a fresh RSA keypair for it. The public half is published at the app's JWKS endpoint; the private half stays inside heimdall-api, encrypted at rest. Tokens for that app (EndUser sessions, M2M access tokens) are signed with the private key. Anyone wanting to verify a token fetches the JWKS and checks the signature.

jose on Node, PyJWT on Python,github.com/lestrrat-go/jwx on Go — every mainstream JWT library knows how to consume a JWKS endpoint. Cache the response for an hour (the endpoint serves aCache-Control: public, max-age=3600) and refresh on kid miss to handle key rotation.

Keys rotate automatically every 90 days. Your service doesn't do anything special — when a new key gets published, your JWKS cache misses on the new kid, you refresh, you keep going. The old key stays valid for a 7-day overlap window so in-flight tokens don't break mid-rotation.

Things customers ask about that live elsewhere:

• Workspace identity — your team's accounts, members, roles inside the workspace. That's the Platform API.
• Transactional email — the actual SMTP delivery for a verification or reset email. Heimdall can fire-and-forget an email through Envoi for you, or you can take the code from the response body and route it through your own SMTP.
• Social features — posts, follows, feeds, moderation. That's Agora, a different service.