Getting Started with the Statisfy SDK

This guide takes you from an empty React app to a working Digital Worker chat embedded in your product.

Prerequisites

A React 18 or 19 application.
A publishable key for your workspace (pk_live_… or pk_test_…) and a JWT secret — generate both in your workspace’s API keys section (see Publishable Keys & Secrets).
A backend that can sign a short-lived JWT with that secret. The secret must never reach the browser.

This guide covers embedding the SDK in your own application, where your backend mints the token. If you’re building a Statisfy-hosted Portal instead, sign-in is handled for you by <PortalAuthGate> and there is no backend to write — see step 2.

1. Install

npm install @statisfy/digital-workers-react

Import the stylesheet once, near your app’s entry point:

import '@statisfy/digital-workers-react/styles.css'

2. Supply a session token

Every SDK request carries a short-lived HS256 bearer token. The SDK never mints it — it calls your getToken callback and sends whatever you return. How you produce it depends on where the SDK is running.

In your own app: your backend signs it

Sign a short-lived JWT with your JWT secret on your server, and expose an endpoint your frontend can call. Statisfy requires the standard iat / exp claims plus the end user’s email, which is how the gateway resolves who is asking.

// YOUR BACKEND — the secret never leaves your server.
import jwt from 'jsonwebtoken'

app.get('/statisfy-token', requireYourOwnAuth, (req, res) => {
  const token = jwt.sign(
    { email: req.user.email },
    process.env.STATISFY_JWT_SECRET,     // your workspace's JWT secret
    { algorithm: 'HS256', expiresIn: '1h' }
  )
  res.json({ token })
})

// YOUR FRONTEND — fetch from your own endpoint; no Statisfy secret here.
async function fetchStatisfyToken(): Promise<string> {
  const res = await fetch('/statisfy-token')
  if (!res.ok) throw new Error(`Token mint failed: ${res.status}`)
  const { token } = await res.json()
  return token
}

Never sign tokens in the browser. Only the publishable key is safe to ship client-side — the JWT secret is a server credential.

In a Statisfy Portal: `<PortalAuthGate>` handles it

A hosted portal has no backend of its own, so its customers sign in passwordless: Statisfy emails a one-time code, and the exchange returns a session token plus a rotating refresh token that keeps them signed in across reloads. You don’t implement any of that. Wrap your portal in <PortalAuthGate> — it renders the sign-in form, owns the token lifecycle, and supplies StatisfyProvider internally, so nothing below it touches getToken:

import { PortalAuthGate, PortalSignOutButton } from '@statisfy/digital-workers-react'
import { portalConfig } from '../portal.config'

export function App() {
  return (
    <PortalAuthGate
      baseUrl={portalConfig.apiBaseUrl}
      portalId={portalConfig.portalId}
      publishableKey={portalConfig.publishableKey}
    >
      <PortalSignOutButton>Sign out</PortalSignOutButton>
      <YourPortal />
    </PortalAuthGate>
  )
}

Every portal template already ships with this wiring, so in practice you only edit what’s inside the gate. Because the gate provides the provider, skip step 3 in a portal. The email the customer receives — sender, subject, body, and how long the code stays valid — is configured per portal on the Auth tab in Portal Studio. See Customizing the Login Email. The address a visitor enters must belong to a customer (a person on an account) of your tenant — that’s how the session is bound to a customer_id. A code is only ever sent to an address that matches; a request for any other address succeeds silently and sends nothing, so the sign-in screen can’t be used to probe your customer list.

The session token is short-lived (default 1 hour). <PortalAuthGate> re-mints it silently before it expires using the stored refresh token, so customers stay signed in without seeing the form again.

Only the portal sign-in produces a customer_id claim, and the project endpoints require one. With a token your own backend signed, the Digital Worker chat works but ProjectModule / useProject return 401 not_a_portal_session.

If you need the raw endpoints — you’re not using React, or you’re building your own sign-in UI — see Portal sign-in. The createPortalAuthClient export gives you the same token lifecycle without the React components.

3. Wrap your app in `StatisfyProvider`

StatisfyProvider supplies the gateway URL and authentication to every SDK component via React context. Set it up once, high in your tree:

import { StatisfyProvider } from '@statisfy/digital-workers-react'
import { useCallback } from 'react'

function Root() {
  // Return the current session token; re-mint when needed. Memoize so the
  // provider doesn't re-render its subtree on every render.
  const getToken = useCallback(async () => {
    return await getCachedOrFreshStatisfyToken() // your caching around the step-2 token source
  }, [])

  return (
    <StatisfyProvider
      baseUrl="https://api.statisfy.com"
      publishableKey="pk_live_your_key"
      getToken={getToken}
    >
      <YourApp />
    </StatisfyProvider>
  )
}

Prop	Type	Required	Description
`baseUrl`	`string`	yes	Statisfy gateway base URL, e.g. `https://api.statisfy.com`.
`getToken`	`() => Promise<string \| null>`	yes	Returns the current session token, per step 2. Called before requests. In a portal, `<PortalAuthGate>` supplies this for you.
`publishableKey`	`string`	no	Your `pk_live_…` / `pk_test_…`. Required for the chat routes.

Pass a stable getToken (wrap it in useCallback). The provider memoizes its context value on getToken identity, so an inline arrow function would re-render every consumer on each render.

4. Render your first component

Now any SDK component works anywhere beneath the provider — no connection props needed.

import { DigitalWorkerChat } from '@statisfy/digital-workers-react'

function SupportPanel() {
  return (
    <DigitalWorkerChat
      workerId="your-digital-worker-uuid"
      workerName="Onboarding Assistant"
      greeting="Hi! How can I help with your onboarding?"
      className="dw-h-[600px]"
    />
  )
}

That’s a fully working chat: streaming replies, conversation history, unread tracking, and inline forms. See Digital Worker Chat for every prop and the headless client. To show a customer’s onboarding project instead, render the Project Module:

import { ProjectModule } from '@statisfy/digital-workers-react'

// Omit projectId to auto-resolve the signed-in customer's onboarding project.
<ProjectModule />

5. Theming (optional)

The SDK’s styles are self-contained and ship inside @layer, so they won’t collide with your app’s CSS — and any plain, unlayered rule you write wins over them without !important. There are two override mechanisms:

--dw-* CSS variables (~31 tokens: colors, radius, elevation, focus rings, status colors, motion), set on :root or any ancestor. Colors are space-separated RGB triplets, not hex.
data-dw-part anatomy selectors to restyle exactly one element.

:root {
  --dw-primary: 13 148 136;     /* brand fill: send button, progress */
  --dw-radius-lg: 4px;          /* cards, bubbles, task groups */
}

[data-dw-part='task-row'] { border-radius: 0; }

Dark mode is opt-in: set data-dw-theme="dark" (or "auto" to follow the visitor’s OS) on your html element. Without the attribute the widget stays light. See Theming for the full variable tables, the guaranteed part names, and the dark palette.

Troubleshooting

401 user_token_invalid

The bearer token’s signature didn’t verify. Make sure getToken returns the session token (in a portal, the one from /auth/verify — not the opaque refresh token), that it hasn’t expired, and that you minted it against the same tenant/environment your gateway points at.

403 not_a_customer

The signed-in user’s email isn’t a person on any account in your tenant. Add them as a contact, or sign in as a known customer.

Components throw 'must be rendered inside <StatisfyProvider>'

An SDK component is mounted outside the provider. Move it beneath <StatisfyProvider> — or, in a portal, beneath <PortalAuthGate>, which supplies the provider itself.

Getting Started

Accounts

People & Contacts

Opportunities

Activities

Views

Filters & Custom Fields

Projects

Tasks

Reports

Workflows

Dashboard

Workbench

Stella AI

Campaigns

Knowledge Base

Approvals

Portals

Statisfy SDK

Digital Workers

Getting Started with the Statisfy SDK

Prerequisites

1. Install

2. Supply a session token

In your own app: your backend signs it

In a Statisfy Portal: `<PortalAuthGate>` handles it

3. Wrap your app in `StatisfyProvider`

4. Render your first component

5. Theming (optional)

Troubleshooting

​Prerequisites

​1. Install

​2. Supply a session token

​In your own app: your backend signs it

​In a Statisfy Portal: <PortalAuthGate> handles it

​3. Wrap your app in StatisfyProvider

​4. Render your first component

​5. Theming (optional)

​Troubleshooting

Prerequisites

1. Install

2. Supply a session token

In your own app: your backend signs it

In a Statisfy Portal: `<PortalAuthGate>` handles it

3. Wrap your app in `StatisfyProvider`

4. Render your first component

5. Theming (optional)

Troubleshooting