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_...

Generate a key from your account settings. Keep it secret — anyone with your key can act as your account. 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. Include an X-User-Email header to tell the API which user's data you're operating on:

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.

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"
}