> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usechar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authentication patterns for dashboard APIs and embedded agent ticket exchange

Char has two authentication surfaces: dashboard APIs and embedded runtime ticket exchange.

## 1) Dashboard/API authentication

Authenticated dashboard and oRPC endpoints use bearer tokens:

```bash theme={null}
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`

```json theme={null}
{
  "publishable_key": "pk_live_...",
  "id_token": "eyJ...",           // optional
  "embedding_origin": "https://app.example.com" // optional
}
```

Response:

```json theme={null}
{
  "ticket": "...",
  "userId": "user_or_pk_id",
  "orgId": "org_...",
  "expiresAt": 1735689600000,
  "expiresIn": 60
}
```

<Info>
  The web component performs this exchange automatically. Most integrations do not call `/api/auth/pk-ticket` directly.
</Info>

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