Skip to main content
@tesouro/embedded-components-react is currently in beta and not yet publicly available on npm. Contact your Tesouro representative to request early access.

​
Overview

The @tesouro/embedded-components-react package provides a set of React components that embed Tesouro functionality directly into your application. Wrap your app in EmbeddedProvider, then render any combination of components — no Next.js required.

​
Before you begin

You will need:
  • A Tesouro client ID and client secret (provided during onboarding)
  • A widget secret (TESOURO_WIDGET_SECRET) — a separate credential used to mint user-scoped widget tokens, also provided during onboarding

​
1. Install

npm install @tesouro/embedded-components-react

​
2. Set up a widget token endpoint

Embedded components authenticate users via short-lived, user-scoped widget tokens — not your API access token. Your backend is responsible for minting these tokens and exposing them via an endpoint.
Widget tokens are user-scoped JWE tokens encrypted with your TESOURO_WIDGET_SECRET. They must be generated server-side to keep your credentials secure.
The endpoint should accept { userId, userEmail } and return { widgetToken }: 
// app/api/widget-token/route.ts
import { EncryptJWT } from 'jose';

export async function POST(req: Request) {
  const { userId, userEmail } = await req.json();

  const widgetToken = await new EncryptJWT({
    sub: userId,
    email: userEmail,
    aud: 'tesouro',
    iss: process.env.TESOURO_CLIENT_ID,
  })
    .setProtectedHeader({ alg: 'A256KW', enc: 'A256GCM' })
    .setExpirationTime('8m')
    .encrypt(Buffer.from(process.env.TESOURO_WIDGET_SECRET!, 'hex'));

  return Response.json({ widgetToken });
}
The required environment variables:
VariableDescription
TESOURO_WIDGET_SECRETHex-encoded secret key for encrypting widget tokens
TESOURO_CLIENT_IDYour Tesouro client ID
TESOURO_CLIENT_SECRETYour Tesouro client secret

​
3. Wrap your app with EmbeddedProvider

Import EmbeddedProvider and configure it with the current user’s identity and your token endpoint: 
import { EmbeddedProvider } from '@tesouro/embedded-components-react';

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <EmbeddedProvider
      userId={currentUser.id}
      userEmail={currentUser.email}
      widgetTokenRefreshUrl="/api/widget-token"
      env="sandbox"
    >
      {children}
    </EmbeddedProvider>
  );
}
PropRequiredDescription
userIdYesYour platform’s unique identifier for the current user
userEmailYesThe current user’s email address
widgetTokenRefreshUrlYesURL of your widget token endpoint
envNo"sandbox" or "production" (default: "sandbox")
widgetTokenRefreshIntervalNoToken refresh interval in ms (default: 300000)
styleOverridesNoTheme customizations (see below)
navigationAdapterNoCustom navigation adapter (see below)

​
(Optional) Navigation adapter

By default, EmbeddedProvider uses browser-native navigation (window.history). Pass a navigationAdapter to integrate with your router: 
'use client';

import { useRouter, usePathname, useSearchParams } from 'next/navigation';
import { EmbeddedProvider } from '@tesouro/embedded-components-react';

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  return (
    <EmbeddedProvider
      userId={currentUser.id}
      userEmail={currentUser.email}
      widgetTokenRefreshUrl="/api/widget-token"
      navigationAdapter={{
        push: (url) => router.push(url),
        replace: (url) => router.replace(url),
        pathname,
        searchParams: new URLSearchParams(searchParams.toString()),
      }}
    >
      {children}
    </EmbeddedProvider>
  );
}

​
(Optional) Style overrides

Customize the look and feel to match your platform: 
<EmbeddedProvider
  userId={currentUser.id}
  userEmail={currentUser.email}
  widgetTokenRefreshUrl="/api/widget-token"
  styleOverrides={{
    primaryColor: '#1a5eea',
    fontFamily: 'Inter, sans-serif',
  }}
>
  {children}
</EmbeddedProvider>

​
Next steps