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.

A “user” in Tesouro is an identity inside a single organization that the platform recognises by its sub and email claims. Your backend already has its own user records — the integration job is to translate those records into Tesouro-scoped tokens at the moment a user touches the platform, either through your backend or through an embedded UI.

​
Identity model

Tesouro never issues passwords or runs a login flow for end users. You bring the identity in a JWT — minted by your OIDC provider — and Tesouro accepts the claims at face value.
ClaimSourceWhat it means
subYour platformThe user’s stable identifier in your system. Freeform string. Reused across sessions; the same user keeps the same sub.
emailYour platformThe user’s email. Used for user lookup and for invitation emails on the authorized users flow.
A user has a home organization — the one the OIDC application is provisioned against — and is created there on first sign-in. The same sub presented under two different OIDC applications is treated as two unrelated identities. What the user can do across organizations depends on the role and permissions you assign them; SMB end users stay within their own org, while platform operators (VSPs, banks, ISOs) can be granted scopes that reach into descendants of their home org.

​
Two token shapes

Whether you need a token-exchange access token or a widget JWE depends on what is making the call.

Backend acting on a user's behalf

Your backend wants to call Tesouro’s REST API for a specific end user. Use OAuth 2.0 Token Exchange (RFC 8693) to swap a partner-issued user JWT for a Tesouro access token. Send Authorization: Bearer <access_token> on subsequent calls.

Browser running embedded UI

An embedded component (React or web component) needs to authenticate as the current user without holding your OAuth client secret. Your backend mints a short-lived JWE encrypted with TESOURO_WIDGET_SECRET; the widget presents that token to the platform.
The two are not interchangeable. A widget JWE will not authenticate a REST call you make from your backend, and a token-exchange access token will not load an embedded widget. If you need both — for example a backend cron job that pulls balances and a customer-facing dashboard that shows them — issue both.

​
Where to next

API access

Token exchange for backend calls made on a specific user’s behalf.

Widget tokens

JWE tokens for embedded UI components running in the browser.

Authorized users

Add users to an organization beyond the primary controller — no application KYC.