Recipes

The guides in Build with identity explain one idea each. A recipe takes several of them and shows them working together on a concrete task. There are three: protecting an API in Node and Express, signing one person in with nothing but curl, and building an application that copes with every answer a person can give on the consent screen.

They are for developers who learn by following a complete example, and for anyone porting the flow to a language the SDK does not cover. Each recipe says what it does not cover, so you know where to go next.

A recipe sits on one of three seams in an integration. The first is the edge of your API, where a token arrives and must be verified. The second is the protocol itself, where you see every request the SDK would make. The third is the person, who can say no, and whose answer your application has to handle.

caller  --token + proof-->  Express middleware  -->  your route      (express-api)you     --curl, step by step-->  identity                             (raw-http-walkthrough)person  --Allow | Deny | take it back-->  your callback handling      (consent-screens)

I have an API and want to accept identity tokens.

1. Protect your API: decide your audience.
2. Protect an API in Node and Express: the middleware.
3. Going-live checklist: the section for APIs.

I want to see exactly what identity expects.

1. Raw HTTP walkthrough: discovery to userinfo.
2. Authorization code with PKCE: the same flow with every parameter.

A third-party app of mine is failing at consent.

1. Consent screens: when it appears and what each answer does.
2. Error handling: what an access denied looks like.

Consent screens answers when a person sees the consent screen: for third-party clients only, the first time and again when you ask for a scope not yet granted, and whenever you force it. It lists what the screen shows, what each choice does to your tokens, how to build for every answer (including an optional scope that was not granted) and how the person can take it back.

Protect an API in Node and Express answers how to verify identity access tokens and DPoP proofs with a small middleware, which audience to pass for a person's token and for a service token, how to check scopes, what to do before you ship and how to test it. It also says what is not covered yet, and that verification does not decide what the caller may do.

Raw HTTP walkthrough answers what each request looks like with no SDK: discovery, the values for one sign-in, the pushed request, the browser step, redeeming the code, calling userinfo, and refreshing and revoking if you asked for offline access. It ends with what to look at when a step fails.

A registered client for the sign-in recipes, and a Node environment for the code. The raw walkthrough needs a second key pair for DPoP, curl and jq. Read Environments and the issuer if you have not configured an issuer before.

Do I have to use Express? No. The middleware only needs the method, the address and two headers. See Protect an API in Node and Express.

Can I skip the SDK? Yes. The raw walkthrough does a full sign-in without it. See Raw HTTP walkthrough.

Can I redraw the consent screen? No, you decide what it asks and handle every answer. See Consent screens.

Does verifying a token tell me what the caller may do? No. See Protect your API.

What if a person denies? Handle the access denied answer with a page that explains their options. See Going-live checklist.

It does not cover every framework. Adapters for the decision client are Available for Next.js, Hono and Express, as described in Decision client and framework adapters. It does not cover single-page or native applications, which have no SDK support yet. Tokens and their claims are in Tokens.