Getting started

Authentication and API keys

Every request carries an API key. Keys can be limited to sending, or to one domain.

Send your key in the Authorization header as a bearer token. Keys look like ck_ followed by an 8-character prefix, an underscore, and a 32-character secret. Chebu stores only a hash of the secret, so a lost key can't be shown again. Create a new one and revoke the old one.

Shell

curl https://api.chebu.io/domains \
  -H "Authorization: Bearer $CHEBU_API_KEY"

Permissions

Permission	Can call
`full_access`	Every endpoint: emails, domains, API keys, webhooks, suppressions, and usage.
`sending_access`	Only `POST /emails` and `POST /emails/batch`. Use it for app servers that just send.

A key can also be limited to one domain with domain_id. It can then only send from addresses on that domain. A sending-only key calling any other endpoint fails with 401 restricted_api_key. A domain-limited key sending from another domain fails with 403 validation_error.

API keys belong to a Business workspace and work while its subscription is active. If a subscription lapses, requests fail until it's renewed.

Create an API key

name is up to 50 characters. permission defaults to full_access. The token in the response is the only time the full key is shown.

POST/api-keys

Request

curl -X POST https://api.chebu.io/api-keys \
  -H "Authorization: Bearer $CHEBU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production app",
    "permission": "sending_access",
    "domain_id": "d91cd9bd-1176-453e-8fc1-35364d380206"
  }'

JSON

{
  "object": "api_key",
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "token": "ck_Ab12Cd34_9f8e7d6c5b4a39281706f5e4d3c2b1a0"
}

List API keys

GET/api-keys

Request

curl https://api.chebu.io/api-keys \
  -H "Authorization: Bearer $CHEBU_API_KEY"

JSON

{
  "object": "list",
  "data": [
    {
      "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
      "name": "Production app",
      "permission": "sending_access",
      "domain_id": "d91cd9bd-1176-453e-8fc1-35364d380206",
      "created_at": "2026-09-27T09:30:00.000Z",
      "last_used_at": "2026-09-27T10:04:12.418Z"
    }
  ]
}

Delete an API key

Deleting a key revokes it. Requests with it fail within about a minute.

DELETE/api-keys/b6d24b8e-af0b-4c3c-be0c-359bbd97381e

Request

curl -X DELETE https://api.chebu.io/api-keys/b6d24b8e-af0b-4c3c-be0c-359bbd97381e \
  -H "Authorization: Bearer $CHEBU_API_KEY"

JSON

{
  "object": "api_key",
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "deleted": true
}