React

@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

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();
  // Resolve the applicant's organization from your own data — never accept it from the client.
  const organizationReference = await getOrganizationReference(userId);

  const widgetToken = await new EncryptJWT({
    sub: userId,
    email: userEmail,
    organization_reference: organizationReference,
    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 });
}

// routes/widget-token.ts
import { EncryptJWT } from 'jose';
import { Router } from 'express';

const router = Router();

router.post('/api/widget-token', async (req, res) => {
  const { userId, userEmail } = req.body;
  // Resolve the applicant's organization from your own data — never accept it from the client.
  const organizationReference = await getOrganizationReference(userId);

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

  res.json({ widgetToken });
});

export default router;

The widget token must include a required organization_reference claim — your opaque, stable identifier for the business the applicant belongs to. Resolve it on your backend from your own data; never accept it from the client.

The required environment variables:

Variable	Description
`TESOURO_WIDGET_SECRET`	Hex-encoded secret key for encrypting widget tokens
`TESOURO_CLIENT_ID`	Your Tesouro client ID
`TESOURO_CLIENT_SECRET`	Your 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>
  );
}

Prop	Required	Description
`userId`	Yes	Your platform’s unique identifier for the current user
`userEmail`	Yes	The current user’s email address
`widgetTokenRefreshUrl`	Yes	URL of your widget token endpoint
`env`	No	`"sandbox"` or `"production"` (default: `"sandbox"`)
`widgetTokenRefreshInterval`	No	Token refresh interval in ms (default: `300000`)
`styleOverrides`	No	Theme customizations (see below)
`navigationAdapter`	No	Custom navigation adapter (see below)

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>
  );
}

import { useNavigate, useLocation } from 'react-router-dom';
import { EmbeddedProvider } from '@tesouro/embedded-components-react';

export function Providers({ children }: { children: React.ReactNode }) {
  const navigate = useNavigate();
  const location = useLocation();

  return (
    <EmbeddedProvider
      userId={currentUser.id}
      userEmail={currentUser.email}
      widgetTokenRefreshUrl="/api/widget-token"
      navigationAdapter={{
        push: (url) => navigate(url),
        replace: (url) => navigate(url, { replace: true }),
        pathname: location.pathname,
        searchParams: new URLSearchParams(location.search),
      }}
    >
      {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

Embedded Banking components — onboarding, balances, transfers, and more
FinOps components — invoicing, expense management, and bill pay

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Overview

Before you begin

1. Install

2. Set up a widget token endpoint

3. Wrap your app with `EmbeddedProvider`

(Optional) Navigation adapter

(Optional) Style overrides

Next steps

​Overview

​Before you begin

​1. Install

​2. Set up a widget token endpoint

​3. Wrap your app with EmbeddedProvider

​(Optional) Navigation adapter

​(Optional) Style overrides

​Next steps

Overview

Before you begin

1. Install

2. Set up a widget token endpoint

3. Wrap your app with `EmbeddedProvider`

(Optional) Navigation adapter

(Optional) Style overrides

Next steps