WorkOS

Connect WorkOS to authenticate end users with your Char agent. Create a WorkOS application, configure the audience claim (which WorkOS doesn’t include by default), and set up Char 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 agent.

Prerequisites

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

Quick Links

WorkOS Dashboard

WorkOS Docs

User Management documentation

AuthKit Documentation

AuthKit SDK reference

Sessions & JWTs

Session and JWT documentation

SDK References

@workos-inc/authkit-react

AuthKit React SDK

@workos-inc/authkit-nextjs

AuthKit Next.js SDK

@workos-inc/authkit-js

AuthKit vanilla JavaScript SDK

@workos-inc/node

WorkOS Node.js SDK

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_)

See WorkOS AuthKit documentation for screenshots of the dashboard setup process.

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 cannot validate that tokens were issued specifically for your application.

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

Setting	Value
Claim Name	`aud`
Claim Value	`char-ai-agent` (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

In the Char 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 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 because it has a unique issuer URL format that includes your client ID.

Token Requirements

Char 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 { useEffect } from 'react';
import "@mcp-b/char/web-component";

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

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

  const CLIENT_ID = 'client_01234567890ABCDEF';

  useEffect(() => {
    if (user) {
      getAccessToken().then((token) => {
        const agent = document.querySelector("char-agent");
        agent?.connect({ idToken: token, clientId: CLIENT_ID });
      });
    }
  }, [user, getAccessToken]);

  return <char-agent />;
}

import { WorkOS } from '@workos-inc/node';
import "@mcp-b/char/web-component";

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

const CLIENT_ID = 'client_01234567890ABCDEF';

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

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

const agent =
  document.querySelector("char-agent") ?? document.createElement("char-agent");

if (!agent.isConnected) {
  document.body.appendChild(agent);
}

agent.connect({ idToken: accessToken, clientId: CLIENT_ID });

// 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 { useEffect } from 'react';
import "@mcp-b/char/web-component";

const CLIENT_ID = 'client_01234567890ABCDEF';

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

  useEffect(() => {
    if (user) {
      getAccessToken().then((token) => {
        const agent = document.querySelector("char-agent");
        agent?.connect({ idToken: token, clientId: CLIENT_ID });
      });
    }
  }, [user, getAccessToken]);

  return <char-agent />;
}

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 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
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 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 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 uses the sub claim (user ID) as the primary identifier
Email is optional for Char authentication

Development vs Production tokens

WorkOS AuthKit development mode uses different token formats:

Development tokens may have different issuer URLs
For testing with Char, 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 (not the upstream IDP token)

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

// This is the WorkOS token, validated against WorkOS JWKS
const agent =
  document.querySelector("char-agent") ?? document.createElement("char-agent");

if (!agent.isConnected) {
  document.body.appendChild(agent);
}

agent.connect({ idToken: accessToken, clientId: CLIENT_ID });

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.

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 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

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

Prerequisites

Quick Links

WorkOS Dashboard

WorkOS Docs

AuthKit Documentation

Sessions & JWTs

SDK References

@workos-inc/authkit-react

@workos-inc/authkit-nextjs

@workos-inc/authkit-js

@workos-inc/node

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

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

​Prerequisites

​Quick Links

WorkOS Dashboard

WorkOS Docs

AuthKit Documentation

Sessions & JWTs

​SDK References

@workos-inc/authkit-react

@workos-inc/authkit-nextjs

@workos-inc/authkit-js

@workos-inc/node

​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

Prerequisites

Quick Links

SDK References

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