Better Auth

Connect Better Auth to authenticate end users with your Char agent. Configure Better Auth as an OIDC provider and set up Char for token validation.

Prerequisites

A Better Auth instance deployed and running
The OIDC Provider and JWT plugins configured
Access to the Char dashboard

Quick Links

Better Auth Docs

Official Better Auth documentation

OIDC Provider Plugin

Configure Better Auth as an OIDC provider

JWT Plugin

JWT token configuration and JWKS

GitHub

Better Auth source code

Installation Guide

Get started with Better Auth

Framework Integrations

React, Next.js, Vue, Svelte, and more

SDK References

better-auth

Better Auth core package

React Integration

React hooks and components

Next.js Integration

Next.js App Router and Pages

Vue Integration

Vue 3 composables

Svelte Integration

SvelteKit integration

All Plugins

OAuth, 2FA, Organizations, and more

Configuration Steps

Install Better Auth

Install the Better Auth package in your application. See the installation guide for details.

npm install better-auth

Configure your environment variables:

BETTER_AUTH_SECRET=your-32-character-secret-minimum
BETTER_AUTH_URL=https://auth.yourapp.com

Configure OIDC Provider and JWT Plugins

Set up Better Auth as an OIDC provider with JWT support for JWKS-based token validation:

// auth.ts
import { betterAuth } from "better-auth";
import { oidcProvider } from "better-auth/plugins";
import { jwt } from "better-auth/plugins";

export const auth = betterAuth({
  // Disable default /token endpoint (OIDC uses /oauth2/token)
  disabledPaths: ["/token"],
  plugins: [
    jwt({
      jwks: {
        // Key rotation settings
        rotationInterval: 60 * 60 * 24 * 30, // 30 days
        gracePeriod: 60 * 60 * 24 * 30,      // 30 days
      },
    }),
    oidcProvider({
      useJWTPlugin: true, // Use asymmetric signing with JWKS
      loginPage: "/sign-in",
      consentPage: "/consent",
      metadata: {
        issuer: "https://auth.yourapp.com",
      },
    }),
  ],
});

Configure Your Application as a Client

oidcProvider({
  useJWTPlugin: true,
  loginPage: "/sign-in",
  trustedClients: [
    {
      clientId: "your-app-client-id",
      clientSecret: "your-client-secret",
      redirectUrls: ["https://yourapp.com/callback"],
      skipConsent: true, // Skip consent for first-party apps
    },
  ],
}),

Configure Char

In the Char Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Custom OIDC as the provider
Enter your Issuer URL (your Better Auth base URL, e.g., https://auth.yourapp.com)
Enter your Client ID (the clientId from your trusted client config)
Click Test Connection to verify
Click Save Changes

Configuration Reference

Char Field	Better Auth Value	Example
Provider Type	Custom OIDC	`oidc`
Issuer URL	Your Better Auth base URL	`https://auth.yourapp.com`
Client ID	Trusted client ID	`your-app-client-id`

Better Auth exposes the JWKS endpoint at /api/auth/jwks by default. The discovery document is available at /.well-known/openid-configuration when using the OIDC Provider plugin.

Using Upstream Identity Providers

If you’re using Better Auth with social login (Google, GitHub, etc.) or enterprise SSO, Better Auth acts as your identity layer. Char validates Better Auth’s tokens, not the upstream provider’s tokens.

Understanding Auth Platforms vs Direct IDPs

Learn how auth platforms like Better Auth issue their own tokens after upstream OAuth flows

Token Requirements

Char validates Better Auth ID tokens with these requirements:

Claim	Requirement
`iss`	Must match your configured issuer URL
`aud`	Must include your configured Client ID
`sub`	Required - used as the user identifier
`exp`	Must not be expired

Better Auth ID Token Claims

When using the JWT plugin with OIDC Provider, tokens include these claims based on requested scopes:

Scope	Claims Included
`openid`	`sub` (user ID)
`profile`	`name`, `picture`, `given_name`, `family_name`
`email`	`email`, `email_verified`

You can add custom claims via the getAdditionalUserInfoClaim callback in the OIDC Provider configuration.

Example: Obtaining and Passing the Token

React (better-auth/react)
Vanilla JavaScript
Next.js (SSR with Ticket)
OIDC Authorization Flow

import { createAuthClient } from "better-auth/react";
import { useEffect, useRef } from "react";
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

const CLIENT_ID = "your-oidc-client-id";

const authClient = createAuthClient({
  baseURL: "https://auth.yourapp.com",
});

function App() {
  const { data: session } = authClient.useSession();
  const agentRef = useRef<WebMCPAgentElement>(null);

  useEffect(() => {
    if (session?.user && agentRef.current) {
      // Get the ID token from your auth flow
      // Better Auth stores session info - you'll need to
      // implement token retrieval based on your setup
      fetchIdToken().then((idToken) => {
        agentRef.current?.connect({ idToken, clientId: CLIENT_ID });
      });
    }
  }, [session]);

  return <char-agent ref={agentRef} />;
}

import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

// After completing the OIDC authorization flow
// and receiving tokens from /oauth2/token endpoint
const CLIENT_ID = "your-oidc-client-id";

async function initializeAgent(idToken: string) {
  const agent = document.querySelector("char-agent") as WebMCPAgentElement
    ?? document.createElement("char-agent") as WebMCPAgentElement;

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

  // Use connect() - keeps token out of DOM
  agent.connect({ idToken, clientId: CLIENT_ID });
}

For Next.js with server-side sessions, exchange the Better Auth token for a short-lived ticket:

// app/dashboard/page.tsx
import { auth } from "@/auth"; // Your Better Auth instance
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { CharAgent } from "./char-agent";

const CLIENT_ID = "your-oidc-client-id";

async function getTicketAuth(idToken: string) {
  const response = await fetch("https://api.usechar.ai/api/auth/ticket", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${idToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      client_id: CLIENT_ID,
    }),
  });
  return response.json();
}

export default async function Dashboard() {
  const session = await auth.api.getSession({
    headers: await headers(),
  });

  if (!session) redirect("/sign-in");

  // Get ID token from your token storage
  const idToken = await getIdTokenFromSession(session);
  const ticketAuth = await getTicketAuth(idToken);

  return (
    <main>
      <CharAgent ticketAuth={ticketAuth} />
    </main>
  );
}

// app/dashboard/char-agent.tsx
"use client";
import { useEffect, useRef } from "react";
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement, TicketAuth } from "@mcp-b/char/web-component";

export function CharAgent({ ticketAuth }: { ticketAuth: TicketAuth }) {
  const agentRef = useRef<WebMCPAgentElement>(null);

  useEffect(() => {
    agentRef.current?.connect({ ticketAuth });
  }, [ticketAuth]);

  return <char-agent ref={agentRef} />;
}

This approach keeps your Better Auth JWT server-side. The ticket is opaque, single-use, and expires in 60 seconds. See SSR Authentication for details.

Initiate the standard OIDC authorization code flow:

// Redirect user to Better Auth authorization endpoint
const authUrl = new URL("https://auth.yourapp.com/oauth2/authorize");
authUrl.searchParams.set("client_id", "your-app-client-id");
authUrl.searchParams.set("redirect_uri", "https://yourapp.com/callback");
authUrl.searchParams.set("response_type", "code");
authUrl.searchParams.set("scope", "openid profile email");
authUrl.searchParams.set("state", crypto.randomUUID());

window.location.href = authUrl.toString();

// In your callback handler, exchange the code for tokens
// POST to /oauth2/token with the authorization code

JWKS Endpoint

Better Auth with the JWT plugin exposes a JWKS endpoint for token verification:

Endpoint	URL
JWKS	`https://auth.yourapp.com/api/auth/jwks`
Discovery	`https://auth.yourapp.com/.well-known/openid-configuration`

The JWKS endpoint returns public keys used to verify token signatures:

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "...",
      "kid": "key-id"
    }
  ]
}

Key Rotation

Better Auth supports automatic key rotation:

jwt({
  jwks: {
    rotationInterval: 60 * 60 * 24 * 30, // Rotate every 30 days
    gracePeriod: 60 * 60 * 24 * 30,      // Keep old keys valid for 30 days
  },
})

During the grace period, both old and new keys are valid, allowing clients to verify tokens signed by either key.

Troubleshooting

INVALID_ISSUER error

The token issuer doesn’t match your configured URL:

Verify the Issuer URL in Char matches your Better Auth metadata.issuer exactly
Ensure you’re using the full URL including https://
Check that BETTER_AUTH_URL environment variable is set correctly

INVALID_AUDIENCE error

The token’s aud claim doesn’t match your configured Client ID:

Ensure the Client ID matches your trustedClients configuration
Verify you’re using the ID token, not a session token
Check that the client is registered in the OIDC Provider plugin

JWKS_FETCH_FAILED error

Char couldn’t reach Better Auth’s JWKS endpoint:

Verify your Better Auth instance is publicly accessible
Check that the JWT plugin is enabled with useJWTPlugin: true
Ensure /api/auth/jwks endpoint is not blocked by middleware
Use Test Connection in the dashboard to verify

Token signature verification failed

If tokens fail signature verification:

Ensure useJWTPlugin: true is set in the OIDC Provider config
Check that the JWT plugin is using the same keys for signing
If keys were recently rotated, wait for cache refresh or clear JWKS cache

Better Auth Features

Better Auth offers additional features that complement Char integration:

Feature	Description
Multi-session Support	Users can have multiple active sessions
Social Login	Google, GitHub, Discord, and 20+ providers
Two-Factor Auth	TOTP and backup codes
Organizations	Multi-tenant support with teams
Session Management	Revoke sessions, track devices

Better Auth Documentation

Explore the full Better Auth documentation

Security Best Practices

Use asymmetric signing with the JWT plugin for production (useJWTPlugin: true)
Configure key rotation to limit the impact of key compromise
Use HTTPS for all endpoints in production
Set appropriate token expiration times
Register only trusted clients with skipConsent: true
Monitor auth logs for suspicious activity

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

Better Auth

Prerequisites

Quick Links

Better Auth Docs

OIDC Provider Plugin

JWT Plugin

GitHub

Installation Guide

Framework Integrations

SDK References

better-auth

React Integration

Next.js Integration

Vue Integration

Svelte Integration

All Plugins

Configuration Steps

Configuration Reference

Using Upstream Identity Providers

Understanding Auth Platforms vs Direct IDPs

Token Requirements

Better Auth ID Token Claims

Example: Obtaining and Passing the Token

JWKS Endpoint

Key Rotation

Troubleshooting

Better Auth Features

Better Auth Documentation

Security Best Practices

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

​Prerequisites

​Quick Links

Better Auth Docs

OIDC Provider Plugin

JWT Plugin

GitHub

Installation Guide

Framework Integrations

​SDK References

better-auth

React Integration

Next.js Integration

Vue Integration

Svelte Integration

All Plugins

​Configuration Steps

​Configuration Reference

​Using Upstream Identity Providers

Understanding Auth Platforms vs Direct IDPs

​Token Requirements

​Better Auth ID Token Claims

​Example: Obtaining and Passing the Token

​JWKS Endpoint

​Key Rotation

​Troubleshooting

​Better Auth Features

Better Auth Documentation

​Security Best Practices

Prerequisites

Quick Links

SDK References

Configuration Steps

Configuration Reference

Using Upstream Identity Providers

Token Requirements

Better Auth ID Token Claims

Example: Obtaining and Passing the Token

JWKS Endpoint

Key Rotation

Troubleshooting

Better Auth Features

Security Best Practices