Back to home

Chesly Docs

Build with the Chesly API — read messages, send messages, and manage your conversations programmatically.

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 — 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 — 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 — list, search, send, edit, delete, react, schedule, cancel scheduled
  • Real-time sync — the SSE event stream at /api/sync
  • Email — list/send/edit/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 / billing
  • Account deletion / GDPR
  • Device pairing or push registration
  • Bridge login flows (interactive QR / cookie / 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–90 days.
  • Revoke tokens you no longer need.
  • If a token is leaked, revoke immediately — issuing a new one doesn't invalidate the old one.