Choosing an integration

Which kind of client fits what you are building, how each one authenticates, and what the TypeScript SDK covers.

On this page

Everything in identity 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 (DPoP). This page helps you pick the client type that matches what you are building, and says honestly where the SDK stops.

The TypeScript SDK#

TDACorp provides a TypeScript SDK to integrators. It is the package @tdacorp/identity-sdk on the public npm registry (pnpm add @tdacorp/identity-sdk), MIT-licensed, and its first release is 2.0.0. The examples in this book import from @tdacorp/identity-sdk.

The SDK is a convenience. Everything it does is plain HTTP that you can do from any language, and the raw HTTP walkthrough shows each request with curl.

Pick your client type#

You are building	Client type	Authenticates with	Grants it holds	SDK support	Status
A server-side web application that signs people in (Next.js, Express with sessions, and similar)	`web`	`private_key_jwt`	`authorization_code`, and `refresh_token` if you want offline access	Relying party and route helpers	Available
The same, written in another language	`web`	`private_key_jwt`	The same	None. Use the protocol directly.	Available
A backend service that calls another service	`service`	`private_key_jwt`	`client_credentials` and `token_exchange`	Service client	Available
An API that receives identity tokens	Resource server, no client of its own is needed to verify	Verifies signatures against the published keys	None	Token and proof verification	Available
An API that asks identity what a person may do	Resource server	A service token	None	Decision client	Available
A single-page application that runs only in the browser	`spa`	None, a public client with a DPoP key	`authorization_code`	None	In development
A native application on a phone or desktop	`native`	None, a public client with a DPoP key	`authorization_code`	None	In development

Web applications#

This is the path the Quickstart takes. Your server holds a private key, signs a short assertion for every call to identity, and keeps tokens on the server. A person never sees a token. See Authorization code with PKCE for the flow and Client authentication for the assertion.

Services#

A service has no browser and no person. It authenticates with its key, receives a token for itself, and exchanges it for a token addressed to the service it wants to call. See Service to service.

Resource servers#

An API does not need to be a client to accept tokens. It verifies the signature, the issuer, the audience and the proof of possession. See Protect your API and the Node and Express recipe.

Single-page and native applications#

Identity has a spa and a native client type. Both are public clients: they hold no key to sign an assertion, they authenticate with none, and the token endpoint then insists on a DPoP proof and PKCE for them. What is missing today is everything around that path. The SDK does not support public clients, this book does not yet walk through a browser-only or on-device flow, and registering such a client yourself is In development. The account area has a Developer apps page with a Register an app button for this tier, which is available only where TDACorp has turned on the self_service_oauth_clients flag (it defaults OFF) and needs a personal workspace. Custom URI schemes and loopback redirects for native applications are In development too, behind the oauth_native_redirect_uris flag, which also defaults OFF.

Where the oauth_cimd flag is on (it defaults OFF), a client can also identify itself by an https address that names a metadata document, with no registration at all. It is narrowed: no client secret, DPoP always required and only the code and refresh grants. See Get a client registered.

If you are building one of these now, ask TDACorp before you start. Do not put a confidential client's key inside a browser bundle or an installed application: a key that ships to users is not a secret.

What is not supported#

Identity does not offer the implicit flow, the resource owner password flow, or the device authorization flow. The discovery document lists code as the only response type, lists four grant types, and publishes device_authorization_endpoint as null on purpose.

Grant type	Used for
`authorization_code`	A person signs in. See Authorization code with PKCE.
`refresh_token`	Staying signed in. See Refresh tokens.
`client_credentials`	A service gets a token for itself. See Client credentials.
`urn:ietf:params:oauth:grant-type:token-exchange`	A service gets a token for another service. See Token exchange.

First party and third party#

A client is either first party, which TDACorp ships, or third party. The difference you will notice is consent: a third-party client shows the person a consent screen the first time, and a first-party client does not. Third-party refresh tokens are also capped in lifetime. See Consent screens and Refresh tokens.