WorkOS Integration

Connect WorkOS to authenticate end users interacting with your Char AI widget. This guide covers creating a WorkOS application, configuring the audience claim (which WorkOS doesn’t include by default), and setting up Char AI for token validation.

Important: WorkOS does not include the aud (audience) claim in tokens by default. You must configure this manually in your WorkOS dashboard. Without audience validation, tokens from other applications using the same WorkOS environment could be used to access your widget.

Prerequisites

A WorkOS account with User Management enabled
Admin access to your WorkOS dashboard
Access to the Char AI dashboard

Quick Links

WorkOS Dashboard

WorkOS Docs

User Management documentation

AuthKit Documentation

AuthKit SDK reference

Session Claims

JWT claims documentation

Configuration Steps

Create or Select Your WorkOS Environment

Sign in to the WorkOS Dashboard
Select your environment (Production or Staging)
Navigate to User Management in the sidebar

WorkOS provides separate Production and Staging environments. Use Staging for development and testing.

Note Your Client ID

From the WorkOS Dashboard:

Navigate to API Keys in the sidebar
Copy your Client ID (starts with client_)

Find your Client ID in the WorkOS API Keys section

Configure the Audience Claim (Critical)

WorkOS does not include the aud claim by default. You must explicitly configure it:

In the WorkOS Dashboard, navigate to Authentication → Sessions
Under Session Configuration, find JWT Claims
Click Add Custom Claim
Configure the audience claim:

Setting	Value
Claim Name	`aud`
Claim Value	Your Client ID (e.g., `client_01234567890ABCDEF`)

Click Save

This step is critical for security. Without the aud claim, Char AI cannot validate that tokens were issued specifically for your application.

Alternatively, you can set a custom audience value that you’ll configure in Char AI:

Setting	Value
Claim Name	`aud`
Claim Value	`char-ai-widget` (or your preferred identifier)

Configure Redirect URIs

In the WorkOS Dashboard:

Navigate to Authentication → Redirects
Add your application’s callback URLs:
- https://yourapp.com/callback (production)
- http://localhost:3000/callback (development)
Add your logout redirect URLs if using sign-out functionality

Configure Char AI

In the Char AI Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Custom OIDC as the provider
Enter your configuration:

Field	Value
Client ID	Your WorkOS Client ID or custom `aud` value
Issuer URL	`https://api.workos.com/user_management/{your-client-id}`

Click Test Connection to verify
Click Save Changes

Configuration Reference

Char AI Field	WorkOS Value	Example
Provider Type	Custom OIDC	`custom_oidc`
Client ID	Your configured `aud` claim value	`client_01234567890ABCDEF`
Issuer URL	WorkOS User Management issuer	`https://api.workos.com/user_management/client_01234567890ABCDEF`

WorkOS uses the Custom OIDC provider type in Char AI because it has a unique issuer URL format that includes your client ID.

Token Requirements

Char AI validates WorkOS tokens with these requirements:

Claim	Requirement
`iss`	Must match `https://api.workos.com/user_management/{client-id}`
`aud`	Must include your configured audience value
`sub`	Required - used as the user identifier (WorkOS user ID)
`exp`	Must not be expired

Standard WorkOS Token Claims

WorkOS tokens include these claims by default:

Claim	Description
`sub`	WorkOS user ID (e.g., `user_01234567890ABCDEF`)
`sid`	Session ID
`org_id`	Organization ID (if user is in an organization)
`role`	User’s role in the organization
`email`	User’s email address

Example: Obtaining and Passing the Token

AuthKit (React)
AuthKit (JavaScript)
Next.js (AuthKit)

import { AuthKitProvider, useAuth } from '@workos-inc/authkit-react';
import { CharWidget } from '@char-ai/widget';
import { useEffect } from 'react';

// Wrap your app with AuthKitProvider
function App() {
  return (
    <AuthKitProvider
      clientId="client_01234567890ABCDEF"
      apiHostname="api.workos.com"
    >
      <YourApp />
    </AuthKitProvider>
  );
}

function YourApp() {
  const { user, getAccessToken } = useAuth();

  useEffect(() => {
    if (user) {
      getAccessToken().then((token) => {
        CharWidget.init({
          siteId: 'your-site-id',
          userToken: token,
        });
      });
    }
  }, [user, getAccessToken]);

  return <div id="char-widget" />;
}

import { WorkOS } from '@workos-inc/node';
import { CharWidget } from '@char-ai/widget';

// Client-side: Use AuthKit
import createAuthKit from '@workos-inc/authkit-js';

const authkit = await createAuthKit({
  clientId: 'client_01234567890ABCDEF',
});

// After user signs in
const { accessToken } = await authkit.getSession();

CharWidget.init({
  siteId: 'your-site-id',
  userToken: accessToken,
});

// app/layout.tsx or pages/_app.tsx
import { AuthKitProvider } from '@workos-inc/authkit-nextjs';

export default function RootLayout({ children }) {
  return (
    <AuthKitProvider>
      {children}
    </AuthKitProvider>
  );
}

// In your component
'use client';
import { useAuth } from '@workos-inc/authkit-nextjs';
import { CharWidget } from '@char-ai/widget';
import { useEffect } from 'react';

export default function ChatWidget() {
  const { user, getAccessToken } = useAuth();

  useEffect(() => {
    if (user) {
      getAccessToken().then((token) => {
        CharWidget.init({
          siteId: 'your-site-id',
          userToken: token,
        });
      });
    }
  }, [user, getAccessToken]);

  return <div id="char-widget" />;
}

WorkOS Organizations

If you’re using WorkOS Organizations for B2B authentication:

Users can belong to multiple organizations
The org_id claim indicates the currently selected organization
Char AI uses the sub claim (user ID) for end-user identification

// Get token for a specific organization
const { accessToken } = await authkit.getSession({
  organizationId: 'org_01234567890ABCDEF',
});

Troubleshooting

INVALID_AUDIENCE error

The most common issue with WorkOS. The token doesn’t include or doesn’t match the configured audience:

Verify aud claim is configured in WorkOS:
- Go to WorkOS Dashboard → Authentication → Sessions
- Check that you’ve added a custom aud claim
- Verify the value matches what you configured in Char AI
Verify the claim value matches exactly:
- If you used your Client ID as the audience, ensure it matches exactly
- Check for any typos or whitespace
Regenerate the token:
- After adding the aud claim, users need to sign in again
- Existing tokens won’t have the new claim

INVALID_ISSUER error

The token issuer doesn’t match the expected format:

Verify your Issuer URL in Char AI follows the format: https://api.workos.com/user_management/{client-id}
Ensure you’re using the correct Client ID (starts with client_)
Check that you haven’t confused Production and Staging environments

JWKS_FETCH_FAILED error

Char AI couldn’t reach WorkOS’s JWKS endpoint:

The JWKS URL is https://api.workos.com/sso/jwks/{client-id}
Verify your Client ID is correct
Use Test Connection in the dashboard to verify connectivity

Token missing email claim

WorkOS access tokens may not always include the email:

This is expected behavior in some configurations
Char AI uses the sub claim (user ID) as the primary identifier
Email is optional for Char AI authentication

Development vs Production tokens

WorkOS AuthKit development mode uses different token formats:

Development tokens may have different issuer URLs
For testing with Char AI, use your Production or Staging environment
Ensure you’ve configured the aud claim in the environment you’re testing

WorkOS SSO Connections

If you’re using WorkOS SSO (SAML/OIDC connections to enterprise IDPs):

Users authenticate through their enterprise IDP (Okta, Azure AD, etc.)
WorkOS issues its own JWT token
Pass the WorkOS token to Char AI (not the upstream IDP token)

// The token from WorkOS after SSO authentication
const { accessToken } = await authkit.getSession();

// This is the WorkOS token, validated against WorkOS JWKS
CharWidget.init({
  siteId: 'your-site-id',
  userToken: accessToken,
});

When using WorkOS SSO, the user’s identity comes from their enterprise IDP, but the token validation is performed against WorkOS’s keys.

Security Best Practices

Always configure the aud claim. This is the single most important security configuration for WorkOS integration with Char AI.

Additional recommendations:

Use separate environments for production and development
Configure appropriate session timeouts in WorkOS dashboard
Enable MFA for sensitive applications
Review authentication logs in WorkOS dashboard for anomalies
Use WorkOS Organizations for B2B scenarios with proper role-based access
Rotate Client Secrets periodically (note: secrets aren’t used for token validation, only for server-side API calls)

JWKS and Token Validation

WorkOS publishes public keys at:

https://api.workos.com/sso/jwks/{client-id}

Char AI fetches these keys to validate token signatures. The keys are cached for 1 hour and automatically refreshed. To manually verify your JWKS endpoint:

curl https://api.workos.com/sso/jwks/client_YOUR_CLIENT_ID | jq

Getting Started

Core Concepts

Guides

Identity Providers

WorkOS

WorkOS Integration

Prerequisites

Quick Links

WorkOS Dashboard

WorkOS Docs

AuthKit Documentation

Session Claims

Configuration Steps

Configuration Reference

Token Requirements

Standard WorkOS Token Claims

Example: Obtaining and Passing the Token

WorkOS Organizations

Troubleshooting

WorkOS SSO Connections

Security Best Practices

JWKS and Token Validation

Getting Started

Core Concepts

Guides

Identity Providers

​WorkOS Integration

​Prerequisites

​Quick Links

WorkOS Dashboard

WorkOS Docs

AuthKit Documentation

Session Claims

​Configuration Steps

​Configuration Reference

​Token Requirements

​Standard WorkOS Token Claims

​Example: Obtaining and Passing the Token

​WorkOS Organizations

​Troubleshooting

​WorkOS SSO Connections

​Security Best Practices

​JWKS and Token Validation

WorkOS Integration

Prerequisites

Quick Links

Configuration Steps

Configuration Reference

Token Requirements

Standard WorkOS Token Claims

Example: Obtaining and Passing the Token

WorkOS Organizations

Troubleshooting

WorkOS SSO Connections

Security Best Practices

JWKS and Token Validation