API key permissions
Choose and change precisely what each application, CLI or agent can do.
Choosing access
Open Settings > API keys. Create a key, give it a meaningful name and select individual permissions. One key can combine multiple scopes. Read and write permissions are independent: granting write does not grant read. Start with the permissions your integration actually needs.
Common combinations
Use these combinations as starting points, then narrow them to your workflow.
| Workflow | Scopes |
|---|---|
| Send transactional email | emails:send |
| Send and monitor delivery or engagement | emails:send, emails:read |
| Read received email | inboxes:read, messages:read |
| Create and inspect test inboxes | inboxes:create, inboxes:read, messages:read |
| Manage sending domains | domains:read, domains:write |
Inboxes
Select only the operations this integration needs.
| Scope | What it allows |
|---|---|
| inboxes:read | List shared application inboxes and their addresses. Does not reveal message bodies. |
| inboxes:create | Create application and test inboxes. Add View inboxes to list them and Read messages to inspect received email. |
| messages:read | Read shared inbox message bodies and attachments. Private business inboxes remain session-only. |
Select only the operations this integration needs.
| Scope | What it allows |
|---|---|
| emails:send | Send email using an allowed sender. Sending quotas, verification and suppression rules still apply. Does not include reading email. |
| emails:read | View sent email records, delivery status, usage and engagement analytics. Sent records may include message content. Also permits listing domains for compatibility. |
Designs
Select only the operations this integration needs.
| Scope | What it allows |
|---|---|
| designs:read | Read reusable HTML email designs and brand settings. |
| designs:write | Create, edit and delete designs, upload brand assets and request AI designs. Add View email designs to browse them. |
Domains
Select only the operations this integration needs.
| Scope | What it allows |
|---|---|
| domains:read | Read domain verification status and the DNS records needed for setup. |
| domains:write | Add, verify and remove sending domains. This does not change records at your DNS provider. |
Webhooks
Select only the operations this integration needs.
| Scope | What it allows |
|---|---|
| webhooks:read | List workspace webhook endpoints and configuration. |
| webhooks:write | Create, update or disable webhook endpoints that receive workspace events. |
Suppression
Select only the operations this integration needs.
| Scope | What it allows |
|---|---|
| suppressions:read | Check recipients blocked from outreach in this workspace. |
| suppressions:write | Block recipients from outreach in this workspace. Does not remove account-wide opt-outs. |
Editing an existing key
An owner or admin can choose Edit permissions, add or remove scopes and save. The secret and expiration stay the same. New requests use the updated permissions; requests already running may finish. An expired or revoked key cannot be edited. Revoking a key removes all access.
Update endpoint
PATCH /api/v2/keys/{id} requires an owner/admin user session and the selected workspace. Send a name and the complete, nonempty scopes array. This replaces the permissions, rather than appending them. Unknown scopes are rejected. The response contains metadata only, never a new secret.
{
"name": "Production delivery",
"scopes": [
"emails:send",
"emails:read"
]
}Credential boundaries
Workspace keys work with HTTP, the CLI and agents, but cannot administer keys, members or billing or access private business inboxes. SMTP credentials and webhook signing secrets are different credentials. Anonymous testing uses a temporary inbox token, not a workspace key. Store all secrets server-side, never in browser code.
Expiry and restrictions
Keys created in the dashboard expire after 30 days. The create API supports 1-365 days. Scopes do not bypass workspace boundaries, domain verification, quotas, suppression rules or sending safeguards. A missing scope produces 403. Invalid, expired or revoked credentials are rejected.