---
title: "API keys API"
description: "API keys in the OneSend API: 5 endpoints. Create and revoke API keys. The full key is returned only once."
url: https://onesend.email/docs/api-reference/api-keys/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# API keys

Create and revoke API keys. The full key is returned only once.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## List API keys

GET `/v1/api-keys`

Needs a dashboard session or an `admin`-scoped API key. Expired keys are listed (with `expiresAt` in the past) until they are revoked.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "name": string,
    "prefix": string,
    "scope": "full" | "send" | "read" | "publishable" | "admin",
    "mode": "live" | "test",
    "lastUsedAt": string or null,
    "createdAt": string,
    "domainIds": [string] or null,
    "mailboxIds": [string] or null,
    "limits": {
      "perHour": number or null,
      "perDay": number or null,
      "maxStreams": number or null
    },
    "recipientAllowlist": [string] or null,
    "expiresAt": string or null,
    "expired": boolean,
    "allowedIps": [string] or null,
    "lastUsedIp": string or null,
    "lastUsedUserAgent": string or null,
    "grants": [string] or null,
    "previousSecretExpiresAt": string or null,
    "createdByUserId": string or null,
    "createdByKeyId": string or null
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Create an API key

POST `/v1/api-keys`

Needs a dashboard session (or an `admin`-scoped live key). The full key is returned once. `scope` defaults to `send`. `test` keys never reach a provider (messages are stored as `sandboxed`). `publishable` keys (`os_pub_…`) can only call `POST /t/conversion` and are safe to put in a web page. `full` keys send, read and manage content; `admin` keys (created from a session only) can also change configuration (providers, routing, domains, webhooks, settings) and manage API keys. `domainIds` limits which sender domains the key may send from. `expiresAt` and `allowedIps` contain a leaked key. A key can only create keys no looser than itself (scope, `domainIds`, `mailboxIds`, `limits`, `recipientAllowlist`, `expiresAt`, `allowedIps`, `grants`): 403 `key_wider_than_creator`. A key can have at most 100 unrevoked keys it created, expired ones included (`ONESEND_MAX_KEYS_PER_KEY`; keys created in the dashboard are not limited): 400 `too_many_keys`. New keys end in a 6-character checksum, so scanners can recognize them offline. The workspace owners get an email.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name`required | `string` |  |
| `scope` | `"full" \| "send" \| "read" \| "publishable" \| "admin"` | Default `send` (least privilege). `full` adds reading and content management; `admin` adds configuration and API keys. Default "send". |
| `mode` | `"live" \| "test"` | Default "live". |
| `domainIds` | `array of string` | At most 50 items. |
| `mailboxIds` | `array of string` | Limit the key to these mailboxes: it can only read, search, stream and send mail for them (403 `mailbox_scope` elsewhere). At most 50 items. |
| `limits` | `object` | Messages per hour and per day (clock hours and UTC days; over the limit: 429 `key_rate_limited` with `retry-after`), and open streams (default 5). |
| `limits.perHour` | `integer or null` | 1 to 100000. |
| `limits.perDay` | `integer or null` | 1 to 1000000. |
| `limits.maxStreams` | `integer or null` | 1 to 50. |
| `recipientAllowlist` | `array of string` | Domains (example.com, with subdomains; \*.example.com for subdomains only) and addresses the key may send to. Other recipients: 403 `recipient_not_allowed`. At most 200 items. |
| `expiresAt` | `string (date-time) or null` | When the key stops working (ISO 8601). After it: 401 `key_expired`. Null or absent: never. |
| `allowedIps` | `array of string or null` | IPv4 and IPv6 addresses and CIDR ranges the key may be used from (203.0.113.7, 10.0.0.0/8, 2001:db8::/32). Elsewhere: 403 `ip_not_allowed`. The address is the client address the server sees (ONESEND\_TRUST\_PROXY decides whether X-Forwarded-For counts). Null or absent: any address. At most 100 items. |
| `grants` | `array of "templates:read" \| "gallery:submit" \| "inbox:agent-changes"` | Extra permissions on top of the scope: `templates:read` (list and read templates) and `gallery:submit` (share templates to the gallery). For example a `send` key for an app that also lists templates. At most 10 items. |

### Responses

`201` Success

```
{
  "id": string,
  "name": string,
  "prefix": string,
  "scope": "full" | "send" | "read" | "publishable" | "admin",
  "mode": "live" | "test",
  "lastUsedAt": string or null,
  "createdAt": string,
  "domainIds": [string] or null,
  "mailboxIds": [string] or null,
  "limits": {
    "perHour": number or null,
    "perDay": number or null,
    "maxStreams": number or null
  },
  "recipientAllowlist": [string] or null,
  "expiresAt": string or null,
  "expired": boolean,
  "allowedIps": [string] or null,
  "lastUsedIp": string or null,
  "lastUsedUserAgent": string or null,
  "grants": [string] or null,
  "previousSecretExpiresAt": string or null,
  "createdByUserId": string or null,
  "createdByKeyId": string or null,
  "key": string
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Update an API key

PATCH `/v1/api-keys/{id}`

Change the name, the expiry (`expiresAt`; null: never) or the allowed addresses (`allowedIps`; null: any). Needs a dashboard session or an `admin`-scoped API key; a key cannot loosen a key beyond its own settings (403 `key_wider_than_creator`), and making an expired key live again with a key counts toward the limit of live keys its creator made (400 `too_many_keys`).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name` | `string` |  |
| `expiresAt` | `string (date-time) or null` | When the key stops working (ISO 8601). After it: 401 `key_expired`. Null or absent: never. |
| `allowedIps` | `array of string or null` | IPv4 and IPv6 addresses and CIDR ranges the key may be used from (203.0.113.7, 10.0.0.0/8, 2001:db8::/32). Elsewhere: 403 `ip_not_allowed`. The address is the client address the server sees (ONESEND\_TRUST\_PROXY decides whether X-Forwarded-For counts). Null or absent: any address. At most 100 items. |

### Responses

`200` Success

```
{
  "id": string,
  "name": string,
  "prefix": string,
  "scope": "full" | "send" | "read" | "publishable" | "admin",
  "mode": "live" | "test",
  "lastUsedAt": string or null,
  "createdAt": string,
  "domainIds": [string] or null,
  "mailboxIds": [string] or null,
  "limits": {
    "perHour": number or null,
    "perDay": number or null,
    "maxStreams": number or null
  },
  "recipientAllowlist": [string] or null,
  "expiresAt": string or null,
  "expired": boolean,
  "allowedIps": [string] or null,
  "lastUsedIp": string or null,
  "lastUsedUserAgent": string or null,
  "grants": [string] or null,
  "previousSecretExpiresAt": string or null,
  "createdByUserId": string or null,
  "createdByKeyId": string or null
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Revoke an API key

DELETE `/v1/api-keys/{id}`

Needs a dashboard session or an `admin`-scoped API key. Both the current secret and a previous one still in its rotation grace period stop working. The keys it created or rotated are revoked too, and the keys those created or rotated, until none is left; the invitations it sent are canceled and the members who joined through them are removed (and, in turn, the invitations those members sent and the members who joined through them). The workspace owners get an email.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Responses

`204` No content

**Errors: 400, 401, 403, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Rotate an API key

POST `/v1/api-keys/{id}/rotate`

Returns a new secret for the same key: same id, name, permissions and restrictions. The old secret keeps working for `gracePeriodSeconds` (default 24 hours, at most 7 days), so you can deploy the new one, then stops. Rotating again during the grace period ends the earlier secret at once. The new secret is returned once. Needs a dashboard session or an `admin`-scoped API key. An API key can rotate only itself and the keys in its own creator chain (that it created, or that those created; 403 `not_in_key_chain` otherwise), and the key that made the rotation is recorded: revoking it, or a leak report about it, revokes the rotated key too, and a leak report of the previous secret of a key last rotated with an API key revokes the whole key. A rotation in the dashboard clears that. The workspace owners get an email.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `id`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `gracePeriodSeconds` | `integer` | How long the old secret keeps working, in seconds (default 86,400: 24 hours; at most 604,800: 7 days; 0: it stops at once). Default 86400. 0 to 604800. |

### Responses

`200` Success

```
{
  "id": string,
  "name": string,
  "prefix": string,
  "scope": "full" | "send" | "read" | "publishable" | "admin",
  "mode": "live" | "test",
  "lastUsedAt": string or null,
  "createdAt": string,
  "domainIds": [string] or null,
  "mailboxIds": [string] or null,
  "limits": {
    "perHour": number or null,
    "perDay": number or null,
    "maxStreams": number or null
  },
  "recipientAllowlist": [string] or null,
  "expiresAt": string or null,
  "expired": boolean,
  "allowedIps": [string] or null,
  "lastUsedIp": string or null,
  "lastUsedUserAgent": string or null,
  "grants": [string] or null,
  "previousSecretExpiresAt": string or null,
  "createdByUserId": string or null,
  "createdByKeyId": string or null,
  "key": string
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
