API Keys

Create, list, and revoke API keys programmatically. Use /me to check the limits and current usage of the key making a request.

---

Scopes

Every key carries one or more scopes that restrict what it can do. Create keys with the minimum scopes needed for each integration.

Scope	Grants access to	Implies
emails:send	Send emails, read your own sends, analytics, starter templates	emails:read
emails:read	Read your own sends, analytics, starter templates	—
domains:read	List and get sending domains	—
domains:manage	Add, verify, update, and delete sending domains	domains:read
keys:read	List API keys	—
keys:write	Revoke API keys	keys:read
webhooks:read	List webhook subscriptions (paid plans only)	—
webhooks:manage	Create, update, and delete webhook subscriptions (paid plans only)	webhooks:read

webhooks:* scopes are only available on paid plans. Requesting them on a free or preview account returns 403 SCOPE_NOT_ALLOWED_FOR_TIER.

---

List API keys

Returns all active keys for the current tenant.

Auth: keys:read scope, or any JWT user.

Query parameters

Parameter	Type	Default	Description
skip	integer	0	Number of results to skip
limit	integer	50	Max results to return (max 100)

Response

200 — array of key objects. The full key value is never returned — only the prefix for identification.

[
  {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "name": "Production server",
    "prefix": "bx_live_Abc1",
    "scopes": ["emails:send"],
    "isActive": true,
    "lastUsedAt": "2026-05-05T14:22:00Z",
    "createdAt": "2026-04-01T09:00:00Z"
  }
]

---

Create an API key

Creates a new key with the specified scopes.

Auth: Dashboard (JWT) only. API-key callers receive 403 jwt_required. A key cannot create other keys — authenticate via the dashboard session for this operation.

Request body

Field		Type	Description
name	required	string	Human-readable label (1–100 characters)
scopes	required	array of strings	One or more scope strings — see Scopes above

Example

{
  "name": "Production server",
  "scopes": ["emails:send"]
}

Response

201 — key object with key field included.

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "name": "Production server",
  "prefix": "bx_live_Abc1",
  "scopes": ["emails:send"],
  "isActive": true,
  "lastUsedAt": null,
  "createdAt": "2026-05-06T10:00:00Z",
  "key": "bx_live_Abc1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

The key field contains the full plaintext key. It will not appear in any subsequent response.

---

Revoke an API key

Revokes the key immediately. Any request currently in-flight with this key will fail at next use. This action cannot be undone.

Auth: keys:write scope, or a JWT admin user.

A key may revoke itself. The DELETE succeeds, and the next request using that key returns 401 invalid_api_key.

Response

204 No Content

---

Introspect the calling key

Returns the tier, current send usage, limits, and allowed content modes for the key making the request. No scope required — any valid API key can call /me.

Auth: API key only. JWT callers receive 403.

Response

200

{
  "tier": "free",
  "usageToday": 124,
  "usageMonth": 3201,
  "limits": {
    "daily": null,
    "monthly": 9000,
    "ratePerMinute": null
  },
  "allowedModes": ["starter_template", "template_id", "html"]
}

Field	Description
tier	Account tier: preview, free, pro, or enterprise
usageToday	Emails sent since the daily reset
usageMonth	Emails sent since the monthly reset
limits.daily	Daily send cap — null means no daily cap
limits.monthly	Monthly send cap
limits.ratePerMinute	Per-minute rate limit — null means no per-minute limit
allowedModes	Content source fields available for sends. Preview accounts: [“starter_template”] only. Full accounts: all three modes.

---

What’s next

You want to…	Go to
Send your first email	Sending emails
Manage sending domains via API	Email domains
Understand the error envelope	Errors
Create keys from the dashboard	API Keys