API keys

These endpoints manage the workspace's sk_live_ API keys, so provisioning can be automated instead of needing a person in the dashboard. They are meant for people and for deployment tooling: a setup script that issues a capped key to a new agent, or a pipeline that rotates a credential. They are deliberately not in /openapi.json, and the MCP server has no tool for them, not even for listing. An agent should be able to send, read and be limited, not rewrite its own limits.

Every endpoint on this page requires domains:write, the closest thing the API has to an administrative scope, so a key that can only send cannot mint a key that can do more. See Authentication for what each scope allows and Limits for agents for how the guardrails behave on a send.

A credential can hand out at most what it holds itself. Creating or editing a key refuses with 403 forbidden any scope the calling key or OAuth token does not hold, and a caller that carries guardrails cannot create or edit a key into something less restricted than itself: the key must have a daily_send_limit no higher than the caller's, an allowed_recipients list inside the caller's, and requires_approval if the caller has it. The details are under Create an API key and Update an API key. A key also may not edit or revoke itself.

Guardrails

A key can carry three limits. They sit on the credential rather than the workspace and are checked on every message the key sends through POST /v1/emails and POST /v1/emails/batch, before anything is stored, because a workspace quota only trips once the damage is done. OAuth access tokens carry none of them.

A guarded key cannot release mail. Deciding an approval (POST /v1/approvals/{id}) is refused with 403 forbidden when the deciding credential is the key that made the send, or is a key with any guardrail: requires_approval, a non-empty allowed_recipients or a daily_send_limit. An OAuth access token cannot decide approvals either (403 forbidden): approvals are decided by a person in the dashboard, or by an API key without guardrails. See Approvals.

The API key object

The key itself and its hash are never part of the object; the key is returned once, in the create response. Every field is always present: a guardrail the key does not have reads null, [] or false.

List API keys

GET /v1/api-keys · requires domains:write

Returns the workspace's keys newest first, cursor-paged, including revoked keys, which have revoked_at set. See Pagination.

Query parameters

Example

curl https://api.sendraven.ai/v1/api-keys \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "8d2f4a6c-1e3b-4c5d-9a7f-0b2d4e6f8a1c",
      "name": "Support agent",
      "last4": "Xk2p",
      "scopes": ["emails:send", "threads:read"],
      "daily_send_limit": 200,
      "allowed_recipients": ["example.com"],
      "requires_approval": true,
      "created_at": "2026-09-15T12:00:00.000Z",
      "last_used_at": "2026-09-15T12:05:00.000Z",
      "revoked_at": null
    },
    {
      "id": "2b4d6f8a-3c5e-4f7a-8b9c-1d3e5f7a9b0c",
      "name": "Old deploy key",
      "last4": "m9Qa",
      "scopes": ["emails:send"],
      "daily_send_limit": null,
      "allowed_recipients": [],
      "requires_approval": false,
      "created_at": "2026-08-01T09:00:00.000Z",
      "last_used_at": "2026-09-10T17:42:00.000Z",
      "revoked_at": "2026-09-12T08:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create an API key

POST /v1/api-keys · requires domains:write

Mints a key and returns it in key. This is the only time the key is shown: only its SHA-256 hash is stored, so it cannot be read back. Store it before doing anything else with the response. A lost key cannot be recovered; revoke it and create another.

Leaving out a guardrail, passing requires_approval: false, or passing an empty allowed_recipients creates the key without that guardrail. Fields not in the table below are ignored.

The new key is checked against the credential making the request, and refused with 403 forbidden when it would be able to do more:

• Every scope in scopes must be one the caller holds.
• If the caller has a daily send limit, daily_send_limit is required and must be no higher than the caller's.
• If the caller has a recipient allowlist, allowed_recipients is required and every entry must be allowed by the caller's list. An address is allowed when the caller's list has that address or its domain; a domain entry (example.com or @example.com) is allowed only when the caller's list has the same domain.
• If the caller has requires_approval, the new key must have requires_approval: true.

An OAuth access token carries no guardrails, so only its scopes limit what it can create.

This response is never stored for idempotency, because it holds the only copy of the key. A retry with the same Idempotency-Key after this request has answered mints another key; a retry that arrives while it is still running waits up to 8 seconds for it to finish and then mints another key too, because there is no stored response to return; if it is still running after the wait, the retry answers 409 idempotency_in_progress. If a request times out, list the keys before retrying and revoke any extra one.

Body

Example

curl https://api.sendraven.ai/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Support agent",
    "scopes": ["emails:send", "threads:read"],
    "daily_send_limit": 200,
    "allowed_recipients": ["example.com"],
    "requires_approval": true
  }'

Response

201 Created

An API key object with key added.

{
  "id": "8d2f4a6c-1e3b-4c5d-9a7f-0b2d4e6f8a1c",
  "name": "Support agent",
  "last4": "Xk2p",
  "scopes": ["emails:send", "threads:read"],
  "daily_send_limit": 200,
  "allowed_recipients": ["example.com"],
  "requires_approval": true,
  "created_at": "2026-09-15T12:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null,
  "key": "sk_live_T3hYb2VmR2t1c1pBbTlxV0RyNnRaXk2p"
}

Errors

Update an API key

PATCH /v1/api-keys/{id} · requires domains:write

Changes a key's name, scopes or guardrails in place, so a limit can be tightened without re-issuing the credential and updating everything that holds it. The key itself does not change.

Fields you leave out are unchanged. scopes and allowed_recipients, when given, replace the whole list. To clear a guardrail, send daily_send_limit: null, allowed_recipients: null (or []), or requires_approval: false: the guardrail is removed from the key, and the response reads daily_send_limit: null, allowed_recipients: [] or requires_approval: false.

Unlike create, unknown fields are refused with 422.

A key may not update itself. Raising your own daily limit or lifting your own approval hold would be the guardrail removing itself on the instruction of the thing it guards, so a request whose id is the calling key answers 403 forbidden. Use a different key or the dashboard. A revoked key cannot be updated either, and answers 409 invalid_state.

An update cannot give a key more than the caller holds, by the same rules as Create an API key, applied to the key as it would be after the update:

• A scope the key does not already have must be one the caller holds. Removing scopes is always allowed, and so is keeping ones the caller lacks.
• A guardrail the request sets or clears must stay within the caller's own: with a caller limited to 100 a day, daily_send_limit: null and daily_send_limit: 500 are refused and 50 is accepted.
• When the update adds a scope, the whole resulting key must be within the caller's guardrails, even the fields the request does not mention, because gaining a scope is gaining power.

Changing only name, or only removing scopes, is never refused by these rules.

Path parameters

Body

Example

curl https://api.sendraven.ai/v1/api-keys/8d2f4a6c-1e3b-4c5d-9a7f-0b2d4e6f8a1c \
  -X PATCH \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "daily_send_limit": 50, "allowed_recipients": null }'

Response

200 OK

The API key object as stored after the update.

{
  "id": "8d2f4a6c-1e3b-4c5d-9a7f-0b2d4e6f8a1c",
  "name": "Support agent",
  "last4": "Xk2p",
  "scopes": ["emails:send", "threads:read"],
  "daily_send_limit": 50,
  "allowed_recipients": [],
  "requires_approval": true,
  "created_at": "2026-09-15T12:00:00.000Z",
  "last_used_at": "2026-09-15T12:05:00.000Z",
  "revoked_at": null
}

Errors

Checked in this order: the body, then the allowed_recipients entries, then whether the key is the caller, then whether it exists, then whether it is revoked, then what the update would grant.

Revoke an API key

DELETE /v1/api-keys/{id} · requires domains:write

Revokes a key. It stops authenticating at once: every request made with it afterwards answers 401. The key stays in the list with revoked_at set, so recent traffic can still be traced to it. Revoking cannot be undone through the API. Revoking a key that is already revoked succeeds again and keeps its original revoked_at.

A key may not revoke itself, because a request that locked out the only key a script holds would leave no way back through the API. Use a different key or the dashboard.

Path parameters

Example

curl https://api.sendraven.ai/v1/api-keys/2b4d6f8a-3c5e-4f7a-8b9c-1d3e5f7a9b0c \
  -X DELETE \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

The key object with revoked_at set, the same object the list shows for it from now on. A revoked key is not deleted, so this is the key rather than a deletion result.

{
  "id": "2b4d6f8a-3c5e-4f7a-8b9c-1d3e5f7a9b0c",
  "name": "Old deploy key",
  "last4": "m9Qa",
  "scopes": ["emails:send"],
  "daily_send_limit": null,
  "allowed_recipients": [],
  "requires_approval": false,
  "created_at": "2026-08-01T09:00:00.000Z",
  "last_used_at": "2026-09-10T17:42:00.000Z",
  "revoked_at": "2026-09-15T12:00:00.000Z"
}

Errors

Checked in this order: whether the key exists, then whether it is the caller.