API Keys

API keys authenticate requests to the Sendry API. Each key belongs to one organization and carries a permission scope. The full key value is returned only once, at creation or transfer time; afterwards only its prefix is shown.

All endpoints require Authorization: Bearer <api_key> (or a dashboard session). Mutations require full_access scope; listing accepts read_only and above.

---

Create API key

POST /v1/api-keys

Requires full_access scope. The full key is returned in this response only. Creating a key is checked against your plan's API key limit.

Request body

Field	Type	Required	Description
name	string	Yes	Human-readable name. 1-100 characters.
scope	string	No	full_access, sending_access, or read_only. Default full_access.
mode	string	No	live or test. Default live. Test keys skip domain verification and do not send real emails.

Example request

{
  "name": "Production Key",
  "scope": "full_access",
  "mode": "live"
}

Response

{
  "id": "key_abc123",
  "name": "Production Key",
  "scope": "full_access",
  "mode": "live",
  "key": "sn_live_9fJ2kQ7wXp3zR8mN5tV1bY6cD4hL0sA",
  "created_at": "2026-05-10T09:00:00Z"
}

---

List API keys

GET /v1/api-keys

Requires read_only scope. The key value is redacted, only key_prefix is returned.

Query parameters

Parameter	Type	Default	Description
limit	number	50	Results per page (1-100).
cursor	string		Pagination cursor from the previous response's next_cursor.

Response

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production Key",
      "scope": "full_access",
      "mode": "live",
      "key_prefix": "sn_live_9fJ2",
      "last_used_at": "2026-05-12T08:15:00Z",
      "created_at": "2026-05-10T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Pagination is cursor-based. Pass next_cursor as the cursor parameter to get the next page.

---

Revoke API key

DELETE /v1/api-keys/:id

Requires full_access scope. Permanently deletes the key. Returns 404 not_found if the key does not belong to your organization.

{
  "deleted": true
}

---

Transfer API key to another organization

POST /v1/api-keys/:id/transfer

Requires full_access scope. Moves the key to the target organization and rotates its secret; the previous owner can no longer use it. The new key value is returned exactly once.

This endpoint requires session authentication (a dashboard session), not an API key: a request authenticated with a bearer API key returns 401 session_required. The caller must own the target organization or be an active owner/admin member of it, otherwise the request returns 403 forbidden_target. Transferring to the same organization returns 400 invalid_target.

Request body

Field	Type	Required	Description
target_org_id	string	Yes	ID of the organization to transfer this key to.

Example request

{
  "target_org_id": "org_def456"
}

Response

{
  "id": "key_abc123",
  "name": "Production Key",
  "scope": "full_access",
  "mode": "live",
  "key": "sn_live_2bX8nQ4mVc7pL1kR9tZ6wY3dH5jF0gS",
  "created_at": "2026-05-10T09:00:00Z"
}

---

Plan limits

Plan	API keys
Free	2
Pro	10
Business	50
Enterprise	Unlimited

Exceeding the limit returns 403 plan_limit_reached.