> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API access

> Use OAuth 2.0 Token Exchange to swap a partner-issued user JWT for a Tesouro access token your backend can use to call the REST API on that user's behalf.

When your backend needs to call the Tesouro REST API as a specific end user — not as your platform credential — exchange a user JWT for a user-scoped Tesouro access token. The resulting token carries the user's organization membership and permissions; everything you do with it is attributed to that user in audit trails.

## When to use it

* The action is logically the user's, not the platform's. Reading "this user's bank accounts", listing "this user's transfers", initiating a transfer the user requested.
* You want Tesouro's authorization layer to enforce the user's role and permissions rather than re-implementing the check in your backend.
* You are calling REST from server-side code. For browser-side calls, use a [widget token](/embedded-banking/guides/users/widget-tokens) instead so you don't ship your client secret to the browser.

If the call is operational — a sync job, a webhook handler, a back-office reconciliation — use the [client credentials](/embedded-banking/guides/authentication/client-credentials) flow instead. Don't impersonate a user just to satisfy a call your platform is making.

## Shape

The mechanism is [OAuth 2.0 Token Exchange (RFC 8693)](https://datatracker.ietf.org/doc/html/rfc8693). Your backend POSTs the user's JWT as a `subject_token` against the Tesouro token endpoint and receives a bearer access token in return. The exact request and response shapes are in the [User token authentication](/embedded-banking/guides/authentication/user-token) reference — this page covers the model, that page covers the wire format.

The `subject_token` you send must be a JWT signed (or, in some configurations, unsigned with `alg: none` — confirm during onboarding) by your OIDC application. It must include:

* `sub` — your stable identifier for the user.
* `email` — the user's email address.

Tesouro rejects the exchange if either claim is empty or missing.

## Token lifetime

The returned access token expires after `expires_in` seconds (typically one hour). Cache it for the user, refresh it just before expiry, and discard it on user logout. Do not store the partner JWT — re-mint a fresh one from your OIDC provider whenever you need to exchange.