Build with identity

This section is for developers whose application signs people in through TDACorp Identity, calls another service with it, or accepts its tokens in an API. It starts with choosing the right kind of client and ends with a checklist for going live. In between are the flows, the tokens, the endpoints, the SDK and a few worked recipes.

It assumes you can run a small web server and follow an HTTP redirect. It does not assume you know OAuth. Everything identity does is standard OAuth 2.0 and OpenID Connect with a few strict choices: every sign-in uses a pushed authorization request and PKCE, an application proves who it is with a signed assertion instead of a shared secret, and tokens are bound to a key you hold. The SDK does the work for TypeScript and Node, and it is on the public npm registry as @tdacorp/identity-sdk. Its name, @tdacorp/identity-sdk, is a placeholder. Each flow is also written in plain HTTP, so another language works.

Your application is a client. It is registered once, by an administrator, with a public key. For each sign-in it pushes the request to identity, sends the browser to identity with a short reference, and trades the returned code for tokens. Your own API is a resource server: it verifies the access token and the proof of possession that comes with it. A backend that calls another backend is a service, which gets a token for itself and exchanges it for one addressed to the service it calls.

person -> your app --pushes request--> identity /par          your app --browser, reference--> identity /authorize --> sign-in pages          your app <--code-- identity          your app --code + proof--> identity /token --> tokens (bound to your key)          your app --access token + proof--> your API  (verifies it)          your API --"may they?"--> identity (decision API)

I am integrating a web application.

1. Choosing an integration: confirm a web client fits.
2. Register a client: what to prepare and send.
3. Quickstart: sign in once.
4. Going live: the checklist.

I am protecting an API.

1. Protect your API: verify the token and the proof.
2. Node and Express recipe: a working middleware.
3. DPoP verification for resource servers: the exact checks.

I want to understand it without the SDK.

1. Raw HTTP walkthrough: every request with curl.
2. Flows: the same flows with every parameter.
3. Endpoints: each endpoint on its own.

Choosing an integration says which client type fits (web, service, resource server, and the in-development single-page and native types). Register a client says what to send an administrator and what you get back. Environments and the issuer says that the issuer is the only address you configure and discovery gives the rest. Quickstart mounts four routes in Next.js. Log users in says what the route helpers guarantee and what you must store.

DPoP says which clients must prove a key and how to keep it. Scopes and consent says how to ask for scopes and a resource, and why there is no roles claim. Service to service covers the two-step token for a caller. Protect your API separates verifying a token, which is Available, from deciding what the caller may do, which is Available too. Back-channel logout ends your session when identity ends one. Step-up and SSO enforcement says how a route asks for a fresher or stronger sign-in and how a client answers. Installations and the entry rule says which organizations your client can sign a person into and why every refusal looks the same. Client ID metadata documents is the In development way to use an https address as a client id, and Pairwise subjects says what a pairwise client sees as sub.

The sub-sections go deeper. Flows has one page per OAuth flow. Recipes has worked examples. Going live has the checklist, error handling, retries and clock skew. Endpoints documents each endpoint. Tokens documents each token and its claims. SDK documents each module.

Node 22.12 or later for the SDK, a registered client and the SDK, @tdacorp/identity-sdk, from the public npm registry. Read How identity works and Sessions and tokens first if the vocabulary is new.

Can I register a client myself? Not a server-side one. An administrator registers it. See Register a client.

Is a client secret used? No. A signed assertion proves who you are. See Client authentication.

Which grants are supported? Authorization code, refresh token, client credentials and token exchange. See Choosing an integration.

Why is my token refused by another service? It is addressed to you, not to them. See Service to service.

Where are the roles? There is no roles claim. See Scopes and consent.

It does not cover the account area people use, which is in Your account, or the administrator console. Lookup tables such as error codes, claims and lifetimes are in the Reference, and a symptom-first path is in Troubleshooting. Single-page and native clients have no SDK support and no walkthrough yet.