Managing API keys
How to mint a Send only, Full, or Support key for one team.
An API key is a Bearer token for the REST API, the SDKs, and MCP. Each key belongs to one team and has a fixed access level.
Before you start
- You need the Team Administrator role to create or delete a key. Other roles can open the page, but they cannot see tokens.
- If you belong to one team and it has no cluster yet, API keys is hidden from the sidebar. Create a cluster first.
Create a key
- Select API keys in the sidebar.
- Select Create API key.
- Enter a Name. Leave it blank to use
API key. - Under Access, choose Send only, Full access, or Support. Send only is the default.
- Select Create API key.
- Copy the Bearer token from the key's row, or open the key and copy it there.
The access level cannot change after you create the key. To switch, create a new key and delete the old one.
Use Send only for apps and integrations that only send mail. If the key leaks, it can only send.
| Access | What the key can do |
|---|---|
| Send only | Send email, including template sends, and check which user the key belongs to. Nothing else. |
| Full access | Clusters, credentials, and sending. Every endpoint in the API reference. |
| Support | Recipient lookup, analytics, status, and suppressions. See Create a Support key. |
Use the key
Send the token in the Authorization header.
The key only works for its own team. Create an API key shows the full response.
Find your team and cluster ids
The API keys page also lists your Team id and the Cluster id of each live cluster. Select an id to copy it.
| Id | Where it goes |
|---|---|
| Team id | /api/v1/teams/… paths and the SDK team id. |
| Cluster id | /clusters/… paths and the X-Capsule-Cluster-Id header. |
A team id in the path that does not match the token's team returns 404 team_mismatch. See Errors.
Keep the key safe
Give each app the least access it needs. Most apps only send, so use a Send only key.
| If this key leaks | Send only | Full access |
|---|---|---|
| Send mail from your verified domains | Yes | Yes |
| Read events, recipients, templates, and sent messages | No | Yes |
| See SMTP passwords and webhook secrets | No | Yes |
| Change clusters, domains, credentials, webhooks, and suppressions | No | Yes |
- Use a Full access key for setup scripts, the CLI, and MCP. Don't deploy one with your app.
- Store keys in environment variables or a secrets manager. Don't commit them, log them, or put them in a URL.
- Send from your server. Never put a key, even a Send only key, in browser or mobile code.
- Create one key per app and environment, so you can delete one without breaking the others.
- If a key leaks, delete it on API keys and create a new one. Deleting stops it straight away.
Delete a key
Select Delete on the key's row, then confirm. Anything that uses the key stops working.