---
search:
  tags:
    - API keys
    - POST
seo:
  description: >-
    Create an API key. Reference for the POST /api-keys endpoint in the
    BillionSend API.
sidebar:
  label: Create an API key
  badge: POST
title: Create an API key
type: openapi-operation
---
`POST /api-keys`

**Request body** (`application/json`, required)

- `name` (string, required)
- `permission` (string)
- `domain_id` (string<uuid> | null) — Restricts the key to this one verified domain of the team: a GET /domains row with shared: false. The key sends only from it and reads and changes only that domain's own resources: its emails, its broadcasts, topics and segments bound to it, its opt-outs, its inboxes and received mail, its own GET, PATCH, DELETE and verify of /domains/{id}, its metrics, and the keys held to the same domain (GET and DELETE /api-keys). Everything that belongs to the team as a whole answers 403 restricted\_api\_key: webhooks, suppressions, templates, contact properties, /usage, /deliverability, /verifications and POST /domains. Omitted or null, the key inherits the calling key's scope: all domains, or the calling key's domain if it is domain-scoped. A domain-scoped calling key cannot name any other domain (403 restricted\_api\_key).
- `inbox_id` (string<uuid> | null) — BillionSend extension: restricts the key to one inbox of the team. It reads that inbox's threads, drafts and received mail and sends only from its address; every other route answers 403 restricted\_api\_key. Needs full\_access, can't be combined with domain\_id, and an inbox holds at most 5 active keys (outside the team's 25).

Request body example:

```json
{
  "name": "string",
  "permission": "full_access",
  "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c",
  "inbox_id": "5127f22b-d152-46dd-aeaa-3a852d9fbfc2"
}
```

**Responses**

- `200` — API key created; the token is returned only here
- `401` — Missing, malformed, unknown or revoked API key
- `403` — Restricted API key: a sending\_access key, an inbox-scoped key, or a domain\_id outside the calling key's domain
- `422` — Validation error
- `429` — Over the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "token": "string"
}
```
