Architecture

Architecture

Vault is a centralized OAuth2 provider organized in three layers: an identity layer of realms and users providing single sign-on, a trust layer of availabilities that scope token validity across services via per-availability key pairs, and an integration layer of clients — backend-only registrations that consume tokens through a thin SDK or raw HTTP. A supporting lifecycle layer (mailers, purge collection) completes the platform. Applications never implement authentication themselves; they delegate to Vault and verify tokens locally.

Layer 1 - Identity: realms and users

The realm is the top-level tenancy unit. It packages a user directory and a registry of clients, and it scopes the SSO session: a user with one login pair authenticates once and is recognized by every client registered in the realm. Sessions live at the realm level, which is what makes single sign-on structural rather than configured — and realms are isolated from each other, with no cross-realm trust.

Layer 2 - Trust: availabilitues and users

Inside a realm, an availability is a logical trust zone for service-level authentication. Clients are registered in the realm directly and linked to an availability; the availability owns a JWKS key pair:

• Vault signs access tokens with the availability’s private key
• Every linked service verifies tokens locally with the public key, fetched over an authenticated REST call at startup - find more on login flow

Any token issued under an availability can be verified by every service linked to that availability — so linking App1’s three services and App2’s five services to one availability puts all eight in a single shared token trust domain, while re-linking App2’s services to a new availability cleanly partitions the two. Availabilities never communicate with each other. Key rotation happen automatically and clients are responsible to refetch the new ones when needed: a token carrying an unseen kid triggers a one-shot keyset refetch before falling back to session refresh. Check out how to manage sessions

Layer 3 — Integration: clients

The client is the application registration: a client_id/client_secret pair, a host binding, and a link to an availability. Integration is deliberately backend-only — secrets and tokens never touch the browser. Services integrate by implementing the documented flow directly: redirect to Vault, receive the callback, exchange the code for tokens, verify incoming tokens locally. The flow is a language-agnostic queue of if-else checks — any language, any framework, no dependencies required. Tokens are self-contained — the access token carries realm, client, roles, availability, and user identity (with coverage controlling which identifiers, uuid and optionally oid, are embedded) — so services derive identity without per-request lookups to Vault.

Layer 4 — Lifecycle: mailers and data hygiene

Supporting cast: mailers (Resend-backed) provide the verification/reset email capability, attachable per-client or per-realm, with headless clients exempt; and the purge API treats deletion as a first-class operation — purged users and clients are recorded in a queryable collection for cross-system deletion sync. GDPR-style compliance is a core primitive, not a bolt-on.