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

# Users

> How partner-side user identities map to Tesouro-scoped tokens — and which token shape to issue when.

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.

| Claim   | Source        | What it means                                                                                                                                     |
| :------ | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sub`   | Your platform | The user's stable identifier in your system. Freeform string. Reused across sessions; the same user keeps the same `sub`.                         |
| `email` | Your platform | The user's email. Used for user lookup and for invitation emails on the [authorized users](/embedded-banking/guides/users/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; business customers stay within their own org, while platform operators such as banks, ISOs, platform partners, and fintech partners 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.

<CardGroup cols={2}>
  <Card title="Backend acting on a user's behalf" icon="server" href="/embedded-banking/guides/users/api-access">
    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.
  </Card>

  <Card title="Browser running embedded UI" icon="window" href="/embedded-banking/guides/users/widget-tokens">
    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.
  </Card>
</CardGroup>

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

<CardGroup cols={3}>
  <Card title="API access" icon="key" href="/embedded-banking/guides/users/api-access">
    Token exchange for backend calls made on a specific user's behalf.
  </Card>

  <Card title="Widget tokens" icon="window" href="/embedded-banking/guides/users/widget-tokens">
    JWE tokens for embedded UI components running in the browser.
  </Card>

  <Card title="Authorized users" icon="user-plus" href="/embedded-banking/guides/users/authorized-users">
    Add users to an organization beyond the primary controller — no application KYC.
  </Card>
</CardGroup>