Skip to main content
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 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, and the JWE payload schema is in the User token authentication reference. The pages below cover the model rather than re-listing the code.

​
Required environment variables

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.