Skip to main content

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.

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 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 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). 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 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.