Learn the concepts

This page gives the recommended reading order for everything under /concepts/. Each page assumes only what the earlier steps cover, so reading top to bottom never requires backtracking.

Read in order

If you are new to OAuth and OIDC, start at Step 1 and read down. Readers usually get lost when a guide jumps to refresh tokens or DPoP before explaining what an "issuer" or a "redirect URI" is, so this order covers those first.

Prefer to run something first? Do the Quick Start (four short pages ending in a working OP), then come back here to learn why each piece exists. After the concepts, pick a task in Use cases.

Skip ahead if you already know X

• Already comfortable with OAuth roles, scopes, and code + PKCE? Jump to Step 4 (Tokens) or Step 6 (Sender-constrained tokens).
• Already running an OP elsewhere and just want to understand the operational surface this library exposes? Skim Step 2 (Setup primitives) for vocabulary, then go to Operations.
• Specifically here for FAPI 2.0? You can read Step 6 (DPoP / mTLS) and then Step 7 → FAPI 2.0 primer without the rest, but the primer assumes you already understand sender constraint.

Step 1 — What is OAuth / OIDC?

Start here if any of "OP", "RP", "RS", "JWT", "PKCE" feel unclear.

• OAuth 2.0 / OIDC primer — the three roles, the one flow they always share, and an acronym cheat sheet for the rest of the docs.

Step 2 — Setup primitives

The vocabulary every later page assumes. These pages are not about flows or tokens yet; they cover the strings, URLs, and keys that identify an OP and its clients.

• issuer — the OP's identity URL, the iss claim, and why exactly one canonical form matters.
• Redirect URI — what an RP registers, why exact-match is the modern rule, and how this library validates it.
• Client types — confidential vs public, and which client authentication methods each supports.
• Scopes and claims — what a scope grants, what a claim carries, and how openid / profile / email map to the user-info response.
• Discovery — /.well-known/openid-configuration, what RPs read from it, and what the OP must keep stable.
• JOSE basics — JWS, JWE, JWK, JWKS, kid, and the algorithm names you will see repeated everywhere.

Step 3 — Common flows

The three grants most deployments use. Read them in order: refresh tokens build on the authorization code flow, and client credentials is easiest to understand by comparing it with it.

• Authorization Code + PKCE — the default user-facing flow. PKCE is required for every client unless the deployment declares the OIDCCore profile.
• Refresh tokens — how long-lived sessions work, rotation, and the reuse-detection rule from RFC 9700.
• Client Credentials — service-to-service. No user, no refresh token, just a client authenticating to itself.

Step 4 — Tokens

What the OP actually emits, and why "JWT vs opaque" is a deployment choice rather than a spec choice.

• ID Token vs access token — two tokens, two audiences, two purposes. A common source of bugs.
• Access token format (JWT vs opaque) — when to ship JWT access tokens (RFC 9068), when to keep them opaque, and what introspection costs.

Step 5 — Sessions and consent

Once tokens are issued, the user has a session at the OP and a record of what they consented to. These two pages cover the OP-side state most flows leave behind.

• Sessions and logout — the OP session vs the RP session, RP-Initiated Logout, and Back-Channel Logout.
• Consent — what the consent screen records, when it can be skipped, and how this library models first-party clients.

Step 6 — Sender-constrained tokens

A bearer token means "whoever holds it can use it". A sender-constrained token binds the token to a key the client has to prove it still holds. Read the selection guide first: it tells you whether your deployment needs DPoP or mTLS at all.

• Sender constraint (DPoP / mTLS) — selection guide — when you need it, and how to choose between the two.
• DPoP — proof-of-possession via a per-request signed JWT. The web-friendly choice.
• mTLS — proof-of-possession via the client's TLS certificate. The infrastructure-heavy choice; mandatory in some FAPI deployments.

Step 7 — Advanced topics

Less common flows and profiles. Read these only when you have a concrete reason — for example a TV-style device, a phone-as-authenticator pattern, an inter-service token swap, or a regulator that names FAPI.

• Device Code (RFC 8628) — input-constrained devices: TVs, CLIs, IoT.
• CIBA — push-to-phone authentication where the user has no browser on the device making the request.
• No-browser flows (CIBA vs Device Code) — how to choose between the two when the requesting device has no browser.
• Token Exchange (RFC 8693) — swapping one token for another with different audience or actor.
• JARM (signed authorization response) — having the OP sign the authorization response itself, one of the methods in FAPI 2.0 Message Signing.
• FAPI 2.0 primer — the profile that pins PAR + sender constraint + strict client auth into one set, used by open banking and equivalent regulated APIs.

Step 8 — Help

When the reading order is not the answer to your question.

• FAQ — short answers to recurring questions, organized roughly the same way as this index.