Skip to main content
Char has two authentication surfaces: dashboard APIs and embedded runtime ticket exchange.

​
1) Dashboard/API authentication

Authenticated dashboard and oRPC endpoints use bearer tokens: 
Authorization: Bearer <jwt>
These tokens are validated server-side and may require org context depending on endpoint.

​
2) Embedded agent ticket exchange

Embedded auth uses publishable key ticket exchange: POST /api/auth/pk-ticket 
{
  "publishable_key": "pk_live_...",
  "id_token": "eyJ...",           // optional
  "embedding_origin": "https://app.example.com" // optional
}
Response: 
{
  "ticket": "...",
  "userId": "user_or_pk_id",
  "orgId": "org_...",
  "expiresAt": 1735689600000,
  "expiresIn": 60
}
The web component performs this exchange automatically. Most integrations do not call /api/auth/pk-ticket directly.

​
Error behavior

Common ticket-exchange failures:
  • INVALID_BODY — missing or malformed request body
  • INVALID_KEY — key has invalid format, is not found, or has been revoked
  • ORIGIN_NOT_ALLOWED — request origin does not match the key’s allowed_origins
  • Token verification errors (for invalid/expired id_token)

​
Security best practices

  • Restrict publishable keys to known origins
  • Pass idToken with connect() rather than DOM attributes
  • Rotate and revoke publishable keys from dashboard settings