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

# Widget tokens

> Mint short-lived JWE tokens that authenticate embedded UI components as the current user without exposing OAuth credentials to the browser.

Embedded components — React or web component — need user-scoped credentials to load and to call the API as the signed-in user. They cannot hold your OAuth client secret directly, because anything in the browser is reachable by anyone who can open devtools. The widget token solves this: your backend mints a server-encrypted JWE that wraps an RFC 8693 token-exchange request, and the widget hands that JWE to Tesouro at runtime. The platform decrypts it server-side, performs the exchange, and issues a user-scoped access token the widget then uses.

## When to use it

* An embedded React component or web component is rendering in a browser session that belongs to a specific user.
* Your backend has access to `TESOURO_CLIENT_ID`, `TESOURO_CLIENT_SECRET`, and `TESOURO_WIDGET_SECRET` — the latter is the 32-byte key used to encrypt the JWE.

If the call is from your backend rather than from a widget, use [API access](/embedded-banking/guides/users/api-access) instead.

## Shape

The JWE is encrypted with `A256KW` key wrapping and `A256GCM` content encryption. Its decrypted payload is an RFC 8693 token-exchange request, the same shape your backend would send directly — including `client_id`, `client_secret`, a required `organization_reference` claim (your opaque, stable identifier for the business the applicant belongs to, used to scope application lookups to that organization), and a `subject_token` JWT with the user's `sub` and `email` claims. The widget posts the JWE to Tesouro; Tesouro decrypts it with `TESOURO_WIDGET_SECRET`, runs the exchange, and returns a user-scoped access token to the widget.

The complete encryption code (Next.js and Express examples) lives in the [React integration guide](/embedded-banking/guides/embedded-components/react#2-set-up-a-widget-token-endpoint), and the JWE payload schema is in the [User token authentication](/embedded-banking/guides/authentication/user-token#widget-authentication) reference. The pages below cover the model rather than re-listing the code.

## Required environment variables

| Variable                | Origin             | Purpose                                                                      |
| :---------------------- | :----------------- | :--------------------------------------------------------------------------- |
| `TESOURO_CLIENT_ID`     | Tesouro onboarding | OAuth client identifier; ends up in the JWE payload as `client_id`.          |
| `TESOURO_CLIENT_SECRET` | Tesouro onboarding | OAuth client secret; ends up in the JWE payload as `client_secret`.          |
| `TESOURO_WIDGET_SECRET` | Tesouro onboarding | 32-byte symmetric key used to encrypt the JWE. Never exposed to the browser. |

Tesouro provides all three during onboarding. Treat them with the same care as a database password — store in your secrets manager, rotate on the same cadence as other backend credentials.

## Token lifetime

Widget tokens are short-lived by design — generate one per session, set an `exp` claim around five to ten minutes from issue, and expose a refresh endpoint that re-mints when the widget asks. The default refresh cadence on `EmbeddedProvider` is five minutes; tune `widgetTokenRefreshInterval` if you raise or lower `exp` to match.

A widget token cannot be reused for backend-side REST calls — it is consumed by the widget runtime, and what it produces (the underlying Tesouro access token) never leaves the browser session it was issued for.