API authentication

How to authenticate with the API.

API keys

Every request is authenticated with an API key, sent as a bearer token:

Authorization: Bearer ak_live_...

Org admins create account keys under API Keys in Organization settings — give each a label, and copy the key right away because it's shown only once. You can revoke a key at any time. There are two kinds:

• Account keys cover the whole account. Add X-User-Email (below) to act as one user.
• User keys belong to a single user and only ever see that user's data. Signing in with the CLI mints one of these for you.

Keep keys secret — anyone with a key can act with its access. The CLI handles this for you automatically once you've logged in or configured a profile.

Scoping a request to a user

Most resources (tasks, chats, contacts, calendars, and the rest of the API reference) belong to a specific user, not the account as a whole. With an account key, include an X-User-Email header to tell the API which user's data you're operating on. The email must belong to a user in your account, or the request is refused. A user key doesn't need it:

Authorization: Bearer ak_live_...
X-User-Email: [email protected]

Account-level endpoints (managing users, teams, organizations) use the API key alone, with no X-User-Email header — they're already scoped to the account. Some list endpoints (tasks and chats, for example) also work without the header and return account-wide results.

Rate limits

Requests are rate-limited per endpoint. Reads (GET) have a much higher limit than writes (POST/PUT/PATCH/DELETE), and a handful of heavier write operations are limited more strictly still. If you're building something that makes a lot of API calls in a loop, add a small delay between requests rather than firing them as fast as possible.

When you're rate limited, the API returns 429 Too Many Requests.

Errors

All errors return JSON in the same shape:

{
  "status": 404,
  "error_code": "not_found",
  "error": "Task not found"
}