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

# Client tokens

> Mint short-lived titan_ct_ credentials and enforce session, recipient, action, origin, and rate rules.

Client tokens are short-lived credentials with the `titan_ct_` prefix. They are
designed for browser and mobile use, but they are not JWTs and do not carry
unrestricted API-key authority.

## Mint

Call `POST /api/client-tokens` with a service credential that has
`sessions:manage`:

```json theme={null}
{
  "session": "sess_3f9a2c1e",
  "ephemeralId": "user_42",
  "ttlSeconds": 900
}
```

The response uses the standard success envelope:

```json theme={null}
{
  "success": true,
  "data": {
    "token": "titan_ct_…",
    "expiresAt": "2030-01-01T00:15:00.000Z"
  }
}
```

`ttlSeconds` must be within the bounds documented for the endpoint. The token is
limited to its organization, session, ephemeral ID, and expiry.

## Session rules

Rules are managed independently:

```http theme={null}
GET    /api/sessions/{session}/client-rules
PUT    /api/sessions/{session}/client-rules
DELETE /api/sessions/{session}/client-rules
```

```json theme={null}
{
  "recipientMode": "conversation",
  "allowedActions": "send_message,send_seen,send_typing",
  "rateLimit": 30,
  "maxDaily": 500,
  "allowedOrigins": "https://app.example.com",
  "enabled": true
}
```

`recipientMode` is one of `conversation`, `any`, or `none`. Unknown modes fail
closed. `allowedActions` is a comma-separated list containing only these
values:

```text theme={null}
mcp                     send_message            send_reaction
send_typing             send_seen               read_presence
subscribe_presence      read_contact            widget_start
widget_pair             widget_status           widget_embedded_signup
widget_handoff
```

The `mcp` action permits the protocol handshake. Each MCP tool still passes
through its ordinary session, recipient, action, origin, and rate rules.

## Security behavior

* Client tokens cannot mint other tokens.
* Rules, recipient/conversation state, origin constraints, and rate limits are
  checked after the token authenticates.
* Delete or disable the session rules to stop permitted effects before all
  issued tokens expire.

Use the generated Messaging API endpoint pages for the exact `ClientToken` and
`ClientRules` component fields.