Clerk

Connect Clerk to authenticate end users with your Char widget. Configure your Clerk application and set up Char for token validation.

Clerk provides developer-focused authentication with built-in UI components. This integration uses Clerk’s JWT templates feature for seamless token validation.

Prerequisites

A Clerk account and application
Access to your Clerk Dashboard
Access to the Char dashboard

Quick Links

Clerk Dashboard

Clerk Docs

Clerk documentation

JWT Templates

JWT Templates documentation

React SDK

Clerk React SDK reference

SDK References

@clerk/clerk-react

React SDK for Clerk

@clerk/nextjs

Next.js SDK for Clerk

@clerk/clerk-js

Vanilla JavaScript SDK

Configuration Steps

Create or Select Your Clerk Application

Sign in to the Clerk Dashboard
Select your application (or create a new one)
Note your application instance (Development or Production)

Clerk provides separate Development and Production instances. Use Development for testing and Production for live applications.

Create a JWT Template

By default, Clerk session tokens may not include all required claims. Create a JWT template to ensure proper token format:

Navigate to JWT Templates in the left sidebar
Click New template
Select Blank template
Name it char-ai (or your preferred name)
Configure the template:

{
  "aud": "{{env.CLERK_PUBLISHABLE_KEY}}",
  "email": "{{user.primary_email_address}}",
  "name": "{{user.full_name}}",
  "picture": "{{user.image_url}}"
}

Click Save

The aud claim is critical for security. Using your Publishable Key ensures tokens are scoped to your application.

Note Your Keys and Issuer

From the Clerk Dashboard:

Navigate to API Keys
Copy your Publishable key (starts with pk_)
Find your Issuer URL in JWT Templates → your template → Issuer

The issuer URL format is: https://{your-frontend-api-domain}For example:

Development: https://grateful-macaw-1.clerk.accounts.dev
Production: https://clerk.yourapp.com (or custom domain)

Find your API keys in the Clerk Dashboard

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 Clerk Publishable Key (or configured `aud`)
Issuer URL	Your Clerk Frontend API domain

Click Test Connection to verify
Click Save Changes

Configuration Reference

Char Field	Clerk Value	Example
Provider Type	Custom OIDC	`custom_oidc`
Client ID	Publishable Key or configured audience	`pk_live_...`
Issuer URL	Frontend API domain	`https://clerk.yourapp.com`

Your Clerk Frontend API domain varies based on your setup:

Development: https://{random}.clerk.accounts.dev
Production (default): https://clerk.{your-domain}.com
Production (custom): Your configured custom domain

Token Requirements

Char validates Clerk tokens with these requirements:

Claim	Requirement
`iss`	Must match your Clerk Frontend API domain
`aud`	Must include your configured audience (Publishable Key)
`sub`	Required - Clerk user ID
`exp`	Must not be expired
`azp`	Must match your Publishable Key

Standard Clerk Session Claims

Claim	Description
`sub`	Clerk user ID (e.g., `user_2abc...`)
`azp`	Authorized party (your Publishable Key)
`sid`	Session ID
`email`	User’s email (if configured in template)
`name`	User’s name (if configured in template)
`org_id`	Organization ID (if using Organizations)
`org_role`	Organization role (if using Organizations)

Example: Obtaining and Passing the Token

Clerk React
Next.js (App Router)
Next.js (Pages Router)
Vanilla JavaScript

import { useAuth } from '@clerk/clerk-react';
import { useEffect } from 'react';
import "@mcp-b/embedded-agent/web-component";

function App() {
  const { isSignedIn, getToken } = useAuth();

  useEffect(() => {
    if (isSignedIn) {
      // Get token from your JWT template
      getToken({ template: 'char-ai' }).then((token) => {
        if (token) {
          const agent = document.querySelector("webmcp-agent");
          if (agent) {
            agent.setAttribute("auth-token", token);
          }
        }
      });
    }
  }, [isSignedIn, getToken]);

  return <webmcp-agent />;
}

// App wrapper with ClerkProvider
import { ClerkProvider } from '@clerk/clerk-react';

function Root() {
  return (
    <ClerkProvider publishableKey="pk_live_...">
      <App />
    </ClerkProvider>
  );
}

// app/layout.tsx
import { ClerkProvider } from '@clerk/nextjs';

export default function RootLayout({ children }) {
  return (
    <ClerkProvider>
      <html>
        <body>{children}</body>
      </html>
    </ClerkProvider>
  );
}

// app/components/ChatWidget.tsx
'use client';
import { useAuth } from '@clerk/nextjs';
import { useEffect } from 'react';
import "@mcp-b/embedded-agent/web-component";

export default function ChatWidget() {
  const { isSignedIn, getToken } = useAuth();

  useEffect(() => {
    if (isSignedIn) {
      getToken({ template: 'char-ai' }).then((token) => {
        if (token) {
          const agent = document.querySelector("webmcp-agent");
          if (agent) {
            agent.setAttribute("auth-token", token);
          }
        }
      });
    }
  }, [isSignedIn, getToken]);

  return <webmcp-agent />;
}

// pages/_app.tsx
import { ClerkProvider } from '@clerk/nextjs';

export default function App({ Component, pageProps }) {
  return (
    <ClerkProvider {...pageProps}>
      <Component {...pageProps} />
    </ClerkProvider>
  );
}

// components/ChatWidget.tsx
import { useAuth } from '@clerk/nextjs';
import { useEffect } from 'react';
import "@mcp-b/embedded-agent/web-component";

export default function ChatWidget() {
  const { isSignedIn, getToken } = useAuth();

  useEffect(() => {
    if (isSignedIn) {
      getToken({ template: 'char-ai' }).then((token) => {
        if (token) {
          const agent = document.querySelector("webmcp-agent");
          if (agent) {
            agent.setAttribute("auth-token", token);
          }
        }
      });
    }
  }, [isSignedIn, getToken]);

  return <webmcp-agent />;
}

import Clerk from '@clerk/clerk-js';
import "@mcp-b/embedded-agent/web-component";

const clerk = new Clerk('pk_live_...');
await clerk.load();

if (clerk.user) {
  // Get token with JWT template
  const token = await clerk.session.getToken({
    template: 'char-ai',
  });

  if (token) {
    const agent =
      document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

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

    agent.setAttribute("auth-token", token);
  }
}

Using Session Token (Without JWT Template)

If you prefer to use the default session token without a JWT template:

import { useAuth } from '@clerk/clerk-react';
import "@mcp-b/embedded-agent/web-component";

function App() {
  const { isSignedIn, getToken } = useAuth();

  useEffect(() => {
    if (isSignedIn) {
      // Get default session token (no template)
      getToken().then((token) => {
        if (token) {
          const agent = document.querySelector("webmcp-agent");
          if (agent) {
            agent.setAttribute("auth-token", token);
          }
        }
      });
    }
  }, [isSignedIn, getToken]);

  return <webmcp-agent />;
}

Default session tokens may have the azp claim as the audience instead of aud. Configure Char accordingly or use a JWT template for consistent audience handling.

Clerk Organizations

If you’re using Clerk Organizations for B2B scenarios:

import { useAuth, useOrganization } from '@clerk/clerk-react';
import "@mcp-b/embedded-agent/web-component";

function App() {
  const { isSignedIn, getToken } = useAuth();
  const { organization } = useOrganization();

  useEffect(() => {
    if (isSignedIn && organization) {
      // Token will include org_id and org_role claims
      getToken({ template: 'char-ai' }).then((token) => {
        if (token) {
          const agent = document.querySelector("webmcp-agent");
          if (agent) {
            agent.setAttribute("auth-token", token);
          }
        }
      });
    }
  }, [isSignedIn, organization, getToken]);

  return <webmcp-agent />;
}

Add organization claims to your JWT template:

{
  "aud": "{{env.CLERK_PUBLISHABLE_KEY}}",
  "email": "{{user.primary_email_address}}",
  "org_id": "{{org.id}}",
  "org_name": "{{org.name}}",
  "org_role": "{{org_membership.role}}"
}

Troubleshooting

INVALID_ISSUER error

The issuer URL doesn’t match:

Check your Frontend API domain in Clerk Dashboard → API Keys
Development vs Production: Ensure you’re using the correct environment’s domain
Custom domains: If using a custom domain, use that as the issuer
No trailing slash: The issuer URL should not end with /

INVALID_AUDIENCE error

The token’s audience doesn’t match the configured Client ID:

Verify you’re using a JWT template with the correct aud claim
If using default tokens, check the azp claim value
Ensure the Client ID in Char matches exactly (Publishable Key or custom audience)

getToken returns null

If getToken() returns null:

Ensure the user is signed in (isSignedIn is true)
Check that the JWT template name is correct
Verify the template exists in your Clerk Dashboard
Check the browser console for Clerk errors

JWKS_FETCH_FAILED error

Char couldn’t reach Clerk’s JWKS endpoint:

JWKS endpoint: {issuer}/.well-known/jwks.json
Verify your Frontend API domain is correct
Use Test Connection in the Char dashboard

Token doesn't include custom claims

If custom claims aren’t appearing:

Verify you’re using the correct JWT template name in getToken({ template: 'name' })
Check template syntax in Clerk Dashboard
Ensure the template is enabled

Custom Domains

When using a custom domain with Clerk:

Configure your custom domain in Clerk Dashboard → Domains
Update your issuer URL in Char to match the custom domain
Update your application’s Clerk configuration

<ClerkProvider
  publishableKey="pk_live_..."
  domain="auth.yourapp.com" // Custom domain
>

Security Best Practices

Use JWT templates to control exactly what claims are included
Rotate keys periodically using Clerk’s key rotation feature
Enable MFA for sensitive applications
Use Organizations for proper B2B access control
Monitor sign-in activity in Clerk Dashboard
Configure allowed origins in Clerk Dashboard
Use Production instance for live applications (separate from Development)

Introduction

How-to Guides

Explanation

Prerequisites

Quick Links

Clerk Dashboard

Clerk Docs

JWT Templates

React SDK

SDK References

@clerk/clerk-react

@clerk/nextjs

@clerk/clerk-js

Configuration Steps

Configuration Reference

Token Requirements

Standard Clerk Session Claims

Example: Obtaining and Passing the Token

Using Session Token (Without JWT Template)

Clerk Organizations

Troubleshooting

Custom Domains

Security Best Practices

Introduction

How-to Guides

Explanation

​Prerequisites

​Quick Links

Clerk Dashboard

Clerk Docs

JWT Templates

React SDK

​SDK References

@clerk/clerk-react

@clerk/nextjs

@clerk/clerk-js

​Configuration Steps

​Configuration Reference

​Token Requirements

​Standard Clerk Session Claims

​Example: Obtaining and Passing the Token

​Using Session Token (Without JWT Template)

​Clerk Organizations

​Troubleshooting

​Custom Domains

​Security Best Practices

Prerequisites

Quick Links

SDK References

Configuration Steps

Configuration Reference

Token Requirements

Standard Clerk Session Claims

Example: Obtaining and Passing the Token

Using Session Token (Without JWT Template)

Clerk Organizations

Troubleshooting

Custom Domains

Security Best Practices