# QAuth documentation

> QAuth is an open-source (Apache 2.0), self-hosted OAuth 2.1 and OpenID Connect authorization server for apps, services and AI agents. Agents act for a person through RFC 8693 token exchange with capped scope modes, step-up before dangerous operations and a per-agent audit trail; MCP servers get the MCP authorization profile (revision 2026-07-28), with @qauth-labs/resource-guard on the resource-server side; tokens can carry a hybrid ML-DSA-65 + Ed25519 signature behind a default-off switch. QAuth is ready for production; it stays below 1.0 only because features planned for 1.0 are not finished.

The full text of every page below is at https://docs.qauth.dev/llms-full.txt. The product site is https://qauth.dev (summary for language models: https://qauth.dev/llms.txt).

## Integrate

Pages that add QAuth-issued tokens to an app, an API or an MCP server.

- [Integrate](https://docs.qauth.dev/integrate/): Guides for adding QAuth-issued tokens to an application or MCP server.
- [MCP Quickstart](https://docs.qauth.dev/integrate/mcp-quickstart/): Wire QAuth as the OAuth 2.1 authorization server for an MCP resource server, end to end.
- [OAuth 2.1 Flow](https://docs.qauth.dev/integrate/oauth-flow/): QAuth's OAuth 2.1 / OIDC endpoints with copy-paste curl for every step, to implement a client by hand.
- [Hosted UI](https://docs.qauth.dev/integrate/hosted-ui/): The server-rendered login, consent, and resume screens an integrator's users see during authorization_code + PKCE.
- [API Reference](https://docs.qauth.dev/integrate/api-reference/): Hand-written reference for every path in QAuth's committed OpenAPI spec.
- [Code Examples](https://docs.qauth.dev/integrate/code-examples/): Copy-paste-ready Node/TypeScript and browser clients for QAuth.
- [Agent Authorization](https://docs.qauth.dev/integrate/agent-authorization/): How an AI agent acts on behalf of a user — the is_agent client type, RFC 8693 token exchange, scope modes, step-up authentication, and per-agent audit.
- [Wallet sign-in (OID4VP)](https://docs.qauth.dev/integrate/wallet-login/): The browser wallet-login flow — the asserted-identifier step, the same-device / cross-device choice and the Response Code return leg, fail-closed gating, account linking, and how to turn the flow on.
- [Account API from a backend](https://docs.qauth.dev/integrate/account-api-backend/): How a backend for frontend, such as the account console's, calls the account API — the token it holds, the fresh-authentication challenge it answers, and the refusals it must not retry.

## Operate

Pages that run and operate your own QAuth.

- [Operate](https://docs.qauth.dev/operate/): Guides for self-hosting and running a QAuth instance.
- [Docker Guide](https://docs.qauth.dev/operate/docker/): Running QAuth with Docker Compose — production and development, service details, and troubleshooting.
- [Topology](https://docs.qauth.dev/operate/topology/): How a QAuth deployment is laid out — one host and one issuer per realm on a dedicated host, DNS and TLS per realm, endpoint hosts for server-side callers, service roles and mutual TLS between them, database users, and the reverse proxy in front.
- [Keys](https://docs.qauth.dev/operate/keys/): How QAuth keeps its keys in each realm's encrypted key store behind a KEK — what the store holds, how keys are imported, replaced and added with auth-server:keys:create, the rotation windows, and the JWKS rule for relying parties.
- [Observability Guide](https://docs.qauth.dev/operate/observability/): QAuth's observability surface — structured logging, request-id tracking, auth-event logging, failed-login lockout, health and readiness, Prometheus metrics, events as OpenTelemetry logs, and alerting.
- [Browser Security Model](https://docs.qauth.dev/operate/browser-security/): The session cookie, CSRF protection, and response security headers behind QAuth's /ui/* login and consent flow.
- [Environment-Aware Authorization](https://docs.qauth.dev/operate/environment-authorization/): The environment (development/staging/production) policy-profile dimension — the two knobs, fail-safe defaults, and the operator setup for each deployment shape.
- [PQC Verifier Guide](https://docs.qauth.dev/operate/pqc-verifier-guide/): How token verifiers behave when hybrid post-quantum signing (ADR-005) is enabled — what changes, what doesn't, and what to do if you validate the PQC signature.
- [Upgrades](https://docs.qauth.dev/operate/upgrades/): How to upgrade QAuth — back up the database, run the new version's migration runner, start the new version — the upgrade from 0.1 to 0.2 with its hosts, keys, sessions and roles, and the history of migration 0011, the destructive ADR-002 identity migration.
- [Configuration](https://docs.qauth.dev/operate/configuration/): Every environment key QAuth reads, with its stability tier, role, default and meaning.
- [Published images](https://docs.qauth.dev/operate/images/): The container images each QAuth release publishes, how to run them by digest, how to verify their signature, provenance and SBOM before you do, and how to build your own image with an AuthMethod plugin added.
- [Reverse Proxy](https://docs.qauth.dev/operate/reverse-proxy/): The rules a reverse proxy in front of QAuth follows, proxy-neutrally, and the reference nginx configuration in deploy/reference/proxy that implements them.
- [SSF transmitter](https://docs.qauth.dev/operate/ssf-transmitter/): Turn on QAuth's Shared Signals Framework transmitter, register a receiver, and run the verification event end to end.
- [Service roles](https://docs.qauth.dev/operate/service-roles/): Run the auth server as one process, or split it into web, api, admin, signer and delivery processes with SERVICE_ROLES, and keep keys on the signer only.
- [Accounts](https://docs.qauth.dev/operate/accounts/): How to disable a user account and enable it again, and what disabling ends for good.
- [Sandbox realm](https://docs.qauth.dev/operate/sandbox-realm/): The paired sandbox realm of a live realm — what it shares with the live realm, what it does not, and the rules the database holds.

## Extend

Pages that work on QAuth itself.

- [Extend](https://docs.qauth.dev/extend/): Guides for contributing to QAuth itself.
- [Frontmatter contract](https://docs.qauth.dev/extend/frontmatter/): The frontmatter fields every QAuth docs page sets, and what each one is for.
- [Request lifecycle](https://docs.qauth.dev/extend/architecture/): A walk through apps/auth-server's bootstrap in execution order — which registration orders are load-bearing and which only look it, what the fail-closed boot checks refuse, and the two security invariants a contributor can silently undo.
- [Repository map](https://docs.qauth.dev/extend/repo-map/): The apps/ and libs/ layout, the Nx scope tags and the module boundary constraints derived from them, where new code belongs, and the Windows CRLF gotcha that fails the format check on files you never touched.
- [Testing](https://docs.qauth.dev/extend/testing/): The five tiers — unit, testcontainers integration, the repo-wide coverage gate, the documentation invariants, and the black-box wire suite — what each can and cannot catch, how to run them, and the two caching lessons this repo learned the hard way.
- [Adding a credential provider](https://docs.qauth.dev/extend/adding-a-credential-provider/): The ADR-003 extension point — the CredentialProvider interface, the registry, and createConfiguredProviders as the single registration point, with PasswordProvider as the complete example and WalletProvider as the fail-closed one.
- [The AuthMethod contract](https://docs.qauth.dev/extend/auth-method-contract/): The experimental plugin API for sign-in methods — what an AuthMethod adds to CredentialProvider, the upstream step it serves, what a method is handed, where its routes mount, the test kit that checks a method against the contract, and how to write a plugin in its own repository with @qauth-labs/plugin-sdk.

## Portal & Dashboard

Pages that the developer portal.

- [Portal & Dashboard](https://docs.qauth.dev/portal/): Guides for using the QAuth developer portal and dashboard.
- [Portal guide](https://docs.qauth.dev/portal/guide/): The developer portal's session model, required environment variables, and every flow it implements, each traced to its route and server action.
- [Known gaps](https://docs.qauth.dev/portal/known-gaps/): An honest account of where the developer portal is thinner than it looks — a dashboard card that misreports a shipped feature, and a page nothing links to.
- [Dashboard specification](https://docs.qauth.dev/portal/dashboard-spec/): The specification the developer dashboard is to be built from — four surfaces, two proposed endpoints, and the ordering constraints an implementer must respect.

## Reference

Pages that APIs, events, policies, status and design records.

- [Reference](https://docs.qauth.dev/reference/): Reference material for QAuth's APIs, configuration, and terminology.
- [Status](https://docs.qauth.dev/reference/status/): What has shipped, what is flag-gated, and what is still open — rendered from the single status source.
- [Design records](https://docs.qauth.dev/reference/records/): The ADRs and security review — dated historical documents, rendered from docs/adr/ and docs/security/ in place, plus how to read them.
- [API conventions](https://docs.qauth.dev/reference/api-conventions/): The rules every route of the admin, account and developer APIs follows — paths, names, errors, paging, concurrency, OpenAPI extensions and versioning.
- [Problem types](https://docs.qauth.dev/reference/problem-types/): Every problem type, code and status a QAuth route that is not an OAuth protocol endpoint answers an error with.
- [Events](https://docs.qauth.dev/reference/events/): The event envelope, the payload rules, the versioning rules and every registered event type, generated from the registry in libs/shared/events.
- [Account API](https://docs.qauth.dev/reference/account-api/): The contract of /account/v1-rc.0, the API a signed-in person manages their own account with — the operations, their token rules, the security log, the errors and the versioning rules, generated from libs/shared/account-contract.
- [Experimental features](https://docs.qauth.dev/reference/experimental-features/): Every experimental item of QAuth, its switch, and the four conditions it must meet to become stable, generated from the registry in libs/shared/stability.
- [Interaction API](https://docs.qauth.dev/reference/interaction-api/): The contract every sign-in page uses to reach the engine — the operations, the steps, the errors and the versioning rules of /interaction/v1-rc.0, generated from libs/shared/interaction-contract.
- [SSF events](https://docs.qauth.dev/reference/ssf-events/): The Shared Signals Framework event each QAuth security event is sent as, with its subject and its members, generated from the registry in libs/shared/events.
- [Admin permissions](https://docs.qauth.dev/reference/admin-permissions/): The admin scopes, every permission of the admin API with its class, and the built-in admin roles, generated from the registry in apps/auth-server.
- [Security operations](https://docs.qauth.dev/reference/security-operations/): What makes an admin operation a security operation, the effect tags, every admin operation with its class and effects, and the reserved operation ids, generated from the registry in apps/auth-server.
- [Realm policies](https://docs.qauth.dev/reference/realm-policies/): Every realm policy field with its default, the environment key that seeds it, which way is stricter and when a change is a security operation, generated from the schema in libs/server/realm-policy.
- [Flow graphs](https://docs.qauth.dev/reference/flow-graphs/): QAuth's flows as delurio semantic graphs, rendered as pages, each with its status and its YAML source on GitHub.

## Flow graphs

QAuth's flows are specified as delurio semantic graphs (ADR-021). None of them is approved yet: `captured` records what QAuth does today, `proposed` is a design under review. The YAML on GitHub is the source of record; each page here is a view rendered from it, and the graphs are outside QAuth's 1.0 stability promise.

- [All graphs](https://docs.qauth.dev/graphs/): the rendered pages, one per flow
- [About the graphs](https://docs.qauth.dev/reference/flow-graphs/)
- [Graph sources on GitHub](https://github.com/qauth-labs/qauth/tree/main/graphs)
- [Open the hosted account page, and start its sign-in ceremonies](https://docs.qauth.dev/graphs/flows/account/account-page/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/account/account-page; diagram https://docs.qauth.dev/graphs/flows/account/account-page/flow.mmd
- [Change the account's sign-in methods and sessions from the hosted account page](https://docs.qauth.dev/graphs/flows/account/account-page-changes/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/account/account-page-changes; diagram https://docs.qauth.dev/graphs/flows/account/account-page-changes/flow.mmd
- [Unlink an upstream account from the account](https://docs.qauth.dev/graphs/flows/account/unlink-upstream/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/account/unlink-upstream; diagram https://docs.qauth.dev/graphs/flows/account/unlink-upstream/flow.mmd
- [Enable and disable an AuthMethod plugin in a realm](https://docs.qauth.dev/graphs/flows/admin/plugin-enable/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/admin/plugin-enable; diagram https://docs.qauth.dev/graphs/flows/admin/plugin-enable/flow.mmd
- [Verify an account's address after its correct password](https://docs.qauth.dev/graphs/flows/core/account-verification/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/account-verification; diagram https://docs.qauth.dev/graphs/flows/core/account-verification/flow.mmd
- [Authorize a client for the signed-in user](https://docs.qauth.dev/graphs/flows/core/authorization/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/authorization; diagram https://docs.qauth.dev/graphs/flows/core/authorization/flow.mmd
- [Tell each app a browser session signed in to that the session ended](https://docs.qauth.dev/graphs/flows/core/backchannel-logout/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/backchannel-logout; diagram https://docs.qauth.dev/graphs/flows/core/backchannel-logout/flow.mmd
- [Ask the signed-in person to allow a client's access, as a step of the Interaction API](https://docs.qauth.dev/graphs/flows/core/consent/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/consent; diagram https://docs.qauth.dev/graphs/flows/core/consent/flow.mmd
- [Ask the user to approve a client's access](https://docs.qauth.dev/graphs/flows/core/consent-page/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/consent-page; diagram https://docs.qauth.dev/graphs/flows/core/consent-page/flow.mmd
- [Sign the browser out at an app's request, and send it back to the app](https://docs.qauth.dev/graphs/flows/core/logout/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/logout; diagram https://docs.qauth.dev/graphs/flows/core/logout/flow.mmd
- [Sign out with an access token](https://docs.qauth.dev/graphs/flows/core/logout-token/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/logout-token; diagram https://docs.qauth.dev/graphs/flows/core/logout-token/flow.mmd
- [Sign in with a passkey, prove it on a passkey-bound account, and bind one after a sign-in](https://docs.qauth.dev/graphs/flows/core/passkey/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/passkey; diagram https://docs.qauth.dev/graphs/flows/core/passkey/flow.mmd
- [Register an account with a passkey alone, and recover it with a recovery code](https://docs.qauth.dev/graphs/flows/core/passkey-sign-up/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/passkey-sign-up; diagram https://docs.qauth.dev/graphs/flows/core/passkey-sign-up/flow.mmd
- [Reset a password, the mailbox first, never past another authenticator](https://docs.qauth.dev/graphs/flows/core/password-reset/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/password-reset; diagram https://docs.qauth.dev/graphs/flows/core/password-reset/flow.mmd
- [Redeem a recovery code in place of a lost factor, and show a new set once](https://docs.qauth.dev/graphs/flows/core/recovery-code/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/recovery-code; diagram https://docs.qauth.dev/graphs/flows/core/recovery-code/flow.mmd
- [Decide a sign-in, one round at a time](https://docs.qauth.dev/graphs/flows/core/sign-in/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/sign-in; diagram https://docs.qauth.dev/graphs/flows/core/sign-in/flow.mmd
- [Sign in with a password in the browser](https://docs.qauth.dev/graphs/flows/core/sign-in-page/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/sign-in-page; diagram https://docs.qauth.dev/graphs/flows/core/sign-in-page/flow.mmd
- [Sign in with a password for tokens](https://docs.qauth.dev/graphs/flows/core/sign-in-token/): status `captured` (records what QAuth does today; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/sign-in-token; diagram https://docs.qauth.dev/graphs/flows/core/sign-in-token/flow.mmd
- [Register a password account, the mailbox first](https://docs.qauth.dev/graphs/flows/core/sign-up/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/sign-up; diagram https://docs.qauth.dev/graphs/flows/core/sign-up/flow.mmd
- [Prove a bound TOTP after the first factor, and bind a new one when the MFA policy needs it](https://docs.qauth.dev/graphs/flows/core/totp/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/core/totp; diagram https://docs.qauth.dev/graphs/flows/core/totp/flow.mmd
- [Link an upstream account to an existing account by signing in to it](https://docs.qauth.dev/graphs/flows/federation/upstream-link/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/federation/upstream-link; diagram https://docs.qauth.dev/graphs/flows/federation/upstream-link/flow.mmd
- [Sign in, or sign up, through one of the realm's upstream identity providers](https://docs.qauth.dev/graphs/flows/federation/upstream-sign-in/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/federation/upstream-sign-in; diagram https://docs.qauth.dev/graphs/flows/federation/upstream-sign-in/flow.mmd
- [Sign in at an upstream provider through an AuthMethod](https://docs.qauth.dev/graphs/flows/federation/upstream-step/): status `proposed` (a design under review; not approved); source https://github.com/qauth-labs/qauth/tree/main/graphs/flows/federation/upstream-step; diagram https://docs.qauth.dev/graphs/flows/federation/upstream-step/flow.mmd

## Source

- [Repository](https://github.com/qauth-labs/qauth)
- [Design records (ADRs)](https://docs.qauth.dev/reference/records/)
- [Releases](https://github.com/qauth-labs/qauth/releases)
- [Security policy](https://github.com/qauth-labs/qauth/security/policy)