Set Up Vitable Drops

Every Drop uses the same three-part setup: install the SDK, expose an authenticated backend endpoint that issues bound tokens, and configure VitableConnectProvider in your React application.

Before You Begin

• A Vitable API key stored on your backend. See Authentication.
• A Vitable employee or employer ID for the signed-in user.
• React 18 or later.

1. Install the SDK

npm install @vitable-inc/drops

2. Create a Server-Side Token Endpoint

Your backend must authenticate the caller, confirm that they may access the requested employee or employer, and exchange its API key for a bound access token.

import os
import requests
from flask import Flask, jsonify, request
app = Flask(__name__)
VITABLE_API_URL = os.environ["VITABLE_API_URL"]
VITABLE_API_KEY = os.environ["VITABLE_API_KEY"]
@app.post("/api/vitable/token")
def create_vitable_token():
    payload = request.get_json(silent=True) or {}
    entity_type = payload.get("entity_type")
    entity_id = payload.get("entity_id")
    if entity_type not in {"employee", "employer"} or not entity_id:
        return jsonify(error="A valid entity_type and entity_id are required"), 400
    # Authenticate the caller and authorize access to this entity here.
    response = requests.post(
        f"{VITABLE_API_URL}/v1/auth/access-tokens",
        headers={
            "Authorization": f"Bearer {VITABLE_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "grant_type": "client_credentials",
            "bound_entity": {"type": entity_type, "id": entity_id},
        },
        timeout=10,
    )
    response.raise_for_status()
    token = response.json()
    return jsonify(
        token=token["access_token"],
        expiresIn=token["expires_in"],
    )

3. Configure the Provider

The provider calls your backend on mount and again when the token needs to be refreshed:

import { VitableConnectProvider } from "@vitable-inc/drops/react"
import type { AccessTokenResponse } from "@vitable-inc/drops/react"
import { useCallback } from "react"
import type { PropsWithChildren } from "react"
const VITABLE_WIDGET_URL = "https://app.vitablehealth.com"
function createTokenFetcher(
  entityType: "employee" | "employer",
  entityId: string,
): () => Promise<AccessTokenResponse> {
  return async () => {
    const response = await fetch("/api/vitable/token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        entity_type: entityType,
        entity_id: entityId,
      }),
    })
    if (!response.ok) {
      throw new Error(`Token request failed: ${response.status}`)
    }
    return response.json()
  }
}
type EmployeeDropSessionProps = PropsWithChildren<{ employeeId: string }>
function EmployeeDropSession({ employeeId, children }: EmployeeDropSessionProps) {
  const fetchToken = useCallback(
    createTokenFetcher("employee", employeeId),
    [employeeId],
  )
  return (
    <VitableConnectProvider
      baseUrl={VITABLE_WIDGET_URL}
      fetchToken={fetchToken}
      contextKey={employeeId}
    >
      {children}
    </VitableConnectProvider>
  )
}

Use employee for the Employee Dashboard and employer for both employer widgets.

Provider Props

Token Lifecycle

The SDK fetches a token when the provider mounts, refreshes it before expiration, retries transient fetch failures with backoff, and sends updates to the iframe. Changing contextKey discards the existing session and requests a token for the new context.

Use a stable contextKey that matches the bound entity ID. Never reuse an employee-bound token for another employee or an employer-bound token for another employer.

4. Add a Widget

Continue with the component you need:

• Employee Dashboard
• Employer Benefits
• Employer Billing

Production Checklist

• Authenticate every token request and authorize the requested entity.
• Keep the Vitable API key in server-side secret storage.
• Allow postMessage communication only with the expected Vitable origin.
• Reset contextKey whenever the active employee or employer changes.
• Record token-fetch and widget errors without logging tokens.
• Use @vitable-inc/drops 0.1.6 or later so members can copy their ID card details in the Employee Dashboard. If your page sends a Permissions-Policy header or is itself embedded in a frame, allow clipboard-write for the Vitable origin.

Theming

Every Drop supports theming through the VitableConnectProvider. Pass a theme prop to customize colors, fonts, and color mode so the embedded experience matches your application’s look and feel.

import type { VitableTheme } from "@vitable-inc/drops/core"
const theme: VitableTheme = {
  fontFamily: '"Inter", system-ui, sans-serif',
  primaryColor: "brand",
  colorMode: "light",
  colors: {
    brand: [
      "#eff6ff", "#dbeafe", "#bfdbfe", "#93c5fd", "#60a5fa",
      "#3b82f6", "#2563eb", "#1d4ed8", "#1e40af", "#1e3a8a"
    ],
    gray: [
      "#f8fafc", "#f1f5f9", "#e2e8f0", "#cbd5e1", "#94a3b8",
      "#64748b", "#475569", "#334155", "#1e293b", "#0f172a"
    ],
    dark: [
      "#cbd5e1", "#94a3b8", "#64748b", "#475569", "#334155",
      "#1e293b", "#172033", "#0f172a", "#0b1120", "#020617"
    ],
  },
}

Pass the theme to the provider from step 3. Use the same object for every provider that renders Drops, including employer providers.

<VitableConnectProvider
  baseUrl={VITABLE_WIDGET_URL}
  fetchToken={fetchToken}
  contextKey={employeeId}
  theme={theme}
>
  {children}
</VitableConnectProvider>

Theme Properties

Color Palettes

Widgets read three palettes from colors. Other keys are ignored unless primaryColor names them.

Any palette you leave out keeps Vitable’s default colors for that role. If you use colorMode: "dark" or "system", provide colors.dark so dark surfaces match your brand.

Fonts

Widgets run in an iframe and can’t use web fonts that are loaded only on your page. Name fonts that are installed on your users’ devices, or end fontFamily with a fallback such as system-ui, sans-serif. fontFamily may contain only letters, numbers, spaces, hyphens, commas, and quotes; any other value is ignored.

Theme updates are applied in real time — if your app supports theme switching, the embedded widgets will update automatically when you change the theme prop.