Authentication

The Chesly API uses bearer-token authentication. Every request must include your personal API token in the Authorization header.

Token format

Tokens are 52 characters long and start with the csk_ prefix. For example:

csk_aBcD3fGhIjK1mN0pQrStUvWxYz23456789aBcDefGhIjKlMn

The prefix makes tokens recognizable in code, logs, and CI output, so an accidentally committed token is easy to spot and revoke.

Sending requests

curl https://api.chesly.app/api/rooms \
  -H "Authorization: Bearer csk_..."

Tier enforcement

Tokens are gated on your subscription tier on every request. If your Chesly Plus subscription lapses, all of your tokens immediately stop working and the API returns:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "subscription_expired",
  "message": "API access requires an active Chesly Plus subscription."
}

There is no grace window for tokens. Renewing your subscription instantly re-enables every previously issued token, so there’s no need to reissue.

Revocation

Tokens can be revoked from the iOS app at Settings > Developer > API Tokens. Revocation is immediate; subsequent requests with the revoked token return 401 Unauthorized.

Cross-device reveal

Each token’s secret only exists on the device that created it. We store a hash on the server so we can authenticate requests, but we cannot show you the secret again from a different device.

If you sign in on a new device, you’ll see your existing tokens in the list but won’t be able to reveal them. Either keep using the original device, or revoke and create a fresh token on the new one.

Permitted endpoints

Personal API tokens use a strict allowlist. Hitting any endpoint not on this list returns:

HTTP/1.1 403 Forbidden

{
  "error": "forbidden_for_api_token",
  "message": "This endpoint is not available for personal API tokens."
}

Tokens may access:

  • Rooms: list, get a room, mark read, mute, archive, favorite, pin
  • Messages: readable history and approved text sending. Search history in your local client.
  • Real-time sync: the SSE event stream at /api/sync
  • Email: list, send, edit, and delete messages and threads, manage labels and signatures
  • Reminders: create, list, update, delete
  • Bridges (read-only): list connected accounts and configured platforms

Tokens cannot access:

  • Authentication flows (token rotation, OAuth, crypto auth)
  • Encryption key registration
  • Subscription and billing
  • Account deletion and GDPR
  • Device pairing or push registration
  • Bridge login flows (interactive QR, cookie, or phone code)
  • Operator endpoints (/api/admin/*)
  • Token management itself (/api/developer/tokens): tokens cannot mint or revoke other tokens
  • AI features: translation and conversation summaries run on GPU and are scoped to the iOS app for v1

We default-deny anything not on the allowlist. New endpoints we add to the API are inaccessible to existing tokens until we explicitly opt them in.

Security checklist

  • Never commit a token to a public git repository.
  • Store tokens in environment variables or a secrets manager, never inline in source.
  • Set an expiry when you can. Tokens for one-off scripts should expire in 30 to 90 days.
  • Revoke tokens you no longer need.
  • If a token is leaked, revoke it immediately. Issuing a new one doesn’t invalidate the old one.

Readable personal-token access

Use only Authorization: Bearer csk_.... Room names and message text are readable through the documented endpoints. No private key, signed header, or separate bootstrap is required. Use the MatrixroomId returned by room listing for lookup, history and sending.

NO_SIGNING_KEY means you need to sign in again in Chesly to restore your account key. For a room-binding error, open the conversation in Chesly. Never send private keys to the API.