Skip to main content

​
Authentication

The Char AI API uses Bearer token authentication with WorkOS JWT tokens.

​
Authorization Header

Include your JWT token in the Authorization header of every request: 
Authorization: Bearer <your-jwt-token>

​
Authorization Levels

The API has three authorization levels:
LevelDescriptionRequired Claims
PublicNo authentication requiredNone
ProtectedValid JWT token requiredUser authentication
OrganizationJWT with organization contextorg_id claim
Most endpoints require organization context. Ensure your JWT token includes the org_id claim.

​
Obtaining a Token

JWT tokens are obtained through the WorkOS AuthKit authentication flow:
  1. User authenticates via WorkOS
  2. WorkOS returns a signed JWT token
  3. Include this token in all API requests

​
Token Validation

Tokens are validated on every request. If a token is:
  • Missing: Returns 401 UNAUTHORIZED
  • Invalid or Expired: Returns 401 UNAUTHORIZED
  • Missing Organization Context: Returns 403 FORBIDDEN

​
Error Responses

Authentication errors follow a consistent format: 
{
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Missing or invalid authentication token"
}

​
Security Best Practices

Secure Storage

Never expose JWT tokens in client-side code or version control

Token Rotation

Refresh tokens before they expire to maintain session continuity