Flows

These pages describe each flow as identity implements it: the requests, the parameters, the answers and every refusal. The SDK performs all of them, and each page says what the SDK does for you. They are for developers who want to know what the SDK is doing, who need to review it, or who are building the same thing in another language.

Read these after the guides in Build with identity, not before. The guides tell you what to call. These pages tell you what is on the wire and why a request is refused.

There are two families of flow. In the first a person is involved: the application pushes a request, sends the browser to identity, receives a code and trades it for tokens, then refreshes and finally signs out. In the second a service acts as itself: it gets a token for itself and exchanges it for a token addressed to the service it calls. Two things run through every flow: the client proves who it is with a signed assertion, and the token names the API it is for.

person:   PAR -> authorize -> code -> token -> refresh ... -> end sessionservice:  client credentials -> token exchange -> call the other serviceall:      client authentication (signed assertion), resource indicator (audience)

I am implementing sign-in in a language without an SDK.

1. Client authentication: how the signed assertion is built.
2. Pushed authorization requests: the first request.
3. Authorization code with PKCE: the whole flow with every parameter.
4. Refresh tokens and offline access: staying signed in.

I am building a backend that calls another backend.

1. Client credentials: a token for yourself.
2. Token exchange: a token the other service will accept.
3. Resource indicators: naming the audience.

My refresh keeps failing.

1. Refresh tokens and offline access: rotation and reuse detection.
2. invalid_grant: what each answer means.

Authorization code with PKCE is the sign-in flow end to end: the steps, the values you generate, every parameter identity accepts, what comes back, how to redeem the code and what to check in the ID token. Pushed authorization requests explains why every sign-in starts with a request sent directly to identity, what to send and how the answer and its errors look.

Client authentication explains that identity has no client secrets. A client signs an assertion with a private key, and the page lists every claim and what makes one fail. Refresh tokens and offline access explains when you get one, that each is used once, that reuse of an old one is treated as theft, and that a refresh token is bound to your key.

Client credentials explains how a service gets a token for itself, with no person involved. Token exchange explains how a service trades a token for one addressed to another service, and that an exchange can only narrow. Resource indicators explains how a sign-in names the API an access token is for. RP-initiated logout explains how your application asks identity to end the session too.

Two more flows are described one level up: DPoP and Back-channel logout.

A registered client, described in Register a client. For the person-facing flows, understand Sessions and tokens first. For the service flows, read Delegation and token exchange.

Why must I push the request first? Identity requires it for every client, so request details never travel through the browser. See Pushed authorization requests.

Do I need a client secret? No. See Client authentication.

When do I get a refresh token? When the client holds the refresh grant and the request asked for offline access. See Refresh tokens and offline access.

Can I widen scopes in an exchange? No. See Token exchange.

Is the implicit or the device flow offered? No. See Choosing an integration.

It does not give the exact shape of each endpoint on its own, which is in Endpoints, or the contents of the tokens, which is in Tokens. It does not cover the SDK modules, which are in SDK. Failures from the flows are explained in Troubleshooting.