---
title: API keys
description: Create API keys with full or sending-only access, limit them to a domain or an inbox, and manage them.
---

An API key is the secret your code sends with every request. Create one under **API keys** in the dashboard, or with the API itself. A key is shown once, when you create it, so store it in your secret manager.

```sh
curl https://api.billionsend.com/emails \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@example.com",
    "to": "ada@example.com",
    "subject": "Hi",
    "text": "Hello."
  }'
```

Keys start with `bs_`. BillionSend stores only a hash of the key, so a lost key cannot be shown again: revoke it and create a new one.

## Create a key

In the dashboard, open **API keys** and choose **Create API key**. Owners, admins and developers can do it; see [team roles](/docs/team-roles). Pick:

- **Name**: 1 to 80 characters, so you can tell keys apart. You can rename it later.
- **Permission**: **Full access** or **Sending only**.
- **Domain**: **Any domain**, or one verified domain of your team.
- **Restrict to an inbox** (shown once you have inboxes): the one [inbox](/docs/inboxes) the key is limited to.

With the API:

```sh
curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "permission": "sending_access",
    "domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
  }'
```

The answer is `{ "id": "…", "token": "bs_…" }`: the token appears only here. `GET /api-keys` lists active keys (never their tokens), and `DELETE /api-keys/{id}` revokes one at once; requests using it fail immediately.

## Permission

| Permission | Can |
| --- | --- |
| **Full access** | Use every endpoint: sending, contacts, segments, topics, broadcasts, domains, webhooks, templates, received mail and API keys. A key [limited to one domain](#limit-a-key-to-a-domain) reaches only part of that. |
| **Sending only** | Send emails (`POST /emails`, `POST /emails/batch`) and nothing else. Everything outside sending, and every read of stored mail, answers `403 restricted_api_key`. |

Use a sending-only key in the app that sends transactional mail. A leaked sending-only key cannot read your contacts, change your domains or create other keys.

## Limit a key to a domain

A key limited to a domain works inside that one domain and reaches nothing that belongs to the whole team. A domain must be verified before you can limit a key to it; the shared inbox subdomain cannot be used.

| What | What the key can do |
| --- | --- |
| Sending, emails, received mail, inboxes, unsubscribes, broadcasts | Only that domain's. A request for another domain answers `403 restricted_api_key`. |
| `GET /emails/metrics` | Reads that domain's numbers only; naming another domain in `domain_id` answers `403 restricted_api_key`. |
| `GET /domains` and `/domains/{id}` (read, change, delete, verify) | Lists and touches only its own domain. Any other domain, the shared subdomain included, answers `404`. |
| `/api-keys` | `POST` creates keys limited to the same domain. `GET` lists, and `DELETE` revokes, only keys limited to that domain; any other key answers `404`. |
| Contacts, segments, topics | Allowed. Contacts are the team's shared address book, but the key cannot lift a team-wide unsubscribe. A segment or topic it creates is bound to its own domain, and it cannot unbind one. |
| Webhooks (every method, the signing secret included), suppressions, templates, contact properties, `GET /usage`, `GET /deliverability`, verifications and `POST /domains` | `403 restricted_api_key`: these belong to the whole team. |

Use one for a service that belongs to a single brand: if it leaks, it reaches that brand's domain and nothing else, not your webhooks, your other keys or your other domains.

## Limit a key to an inbox

An inbox key gives an AI agent access to one [inbox](/docs/inboxes) and nothing else. It needs full access, cannot also be limited to a domain, and can read, reply, forward and send drafts only for that inbox, and send only from its address. It stops working when the inbox expires or is deleted.

## Limits

| Limit | Value |
| --- | --- |
| Active keys per team | 25, [SMTP credentials](/docs/smtp) included. Revoke one to create another (`422` otherwise). |
| Active keys per inbox | 5, outside the team's 25. |
| Requests | 600 per minute per key and 3,000 per team; see [API basics](/docs/api-reference/basics). |

## Who can create which key

- In the dashboard, owners, admins and developers create keys.
- A key you create with the API is never broader than the key that created it: a sending-only key can only create sending-only keys, a key limited to a domain can only create keys for that domain (and sees and revokes only those), and an inbox key cannot create keys.
- A key acts with the team role its creator has **today**, checked on every request. The creator is the person who made it in the dashboard (or connected the app that made it); a key made through the API carries the creator of the key that made it. Role does not narrow everyday work: a full-access key sends and manages contacts, broadcasts, domains, webhooks and keys whichever role its creator has (a key limited to one domain is the exception, see above). The high-risk acts (erasing a recipient, removing a suppression, taking back an unsubscribe) need a key whose creator is an owner or admin right now; other keys answer `403 forbidden`. If the creator is demoted, their keys follow the new role from the next request. If they are removed from the team or leave, every API key they made, the keys those keys made and their agent keys stop working at once (`401 invalid_api_key`) and show as revoked; being invited back does not bring them back. See [team roles](/docs/team-roles).

Creating, renaming and revoking a key are recorded in the [audit log](/docs/audit-log).

## Other keys

- **SMTP credentials** are sending-only keys created on the **SMTP** page for the [SMTP relay](/docs/smtp).
- **Agent keys** (`bs_agent_…`) are for the [MCP server](/docs/mcp) only. They are created under **MCP**, are limited to read-only, read and reply, or read and send, and a team holds up to 20. Your regular API keys do not work on the MCP server.
