> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numonic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Create and manage API keys for programmatic sending

# API Keys

API keys authorize server-side requests to the send endpoint. You can create multiple keys — use separate keys for different environments, services, or rotation schedules.

All API key endpoints require **JWT authentication**.

***

## Create an API key

```
POST /api/v1/api-keys
```

Creates a new API key. The full key value is **only returned once at creation time** — store it securely.

### Request

```bash theme={null}
curl -X POST https://api.numonic.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "type": "live"
  }'
```

With optional expiration:

```bash theme={null}
curl -X POST https://api.numonic.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name":       "Temporary Key",
    "type":       "test",
    "expires_at": "2026-12-31T23:59:59Z"
  }'
```

### Body parameters

| Parameter    | Type   | Required | Description                                           |
| ------------ | ------ | -------- | ----------------------------------------------------- |
| `name`       | string | Yes      | A label for this key (e.g. "Production", "Staging")   |
| `type`       | string | Yes      | `live` for production sending, `test` for development |
| `expires_at` | string | No       | ISO 8601 expiration date. Omit for no expiration      |

### Response `201`

```json theme={null}
{
  "id":         "550e8400-e29b-41d4-a716-446655440000",
  "name":       "Production Key",
  "type":       "live",
  "key_prefix": "nmc_live_abc1...",
  "expires_at": null,
  "created_at": "2026-04-09T10:30:00.000Z",
  "key":        "nmc_live_abc123def456ghi789jkl012mno345"
}
```

<Warning>
  The `key` field is only present in the creation response. It cannot be retrieved again — store it in a secrets manager or environment variable immediately.
</Warning>

***

## List API keys

```
GET /api/v1/api-keys
```

Returns all API keys for your account. The full key value is not included.

### Request

```bash theme={null}
curl https://api.numonic.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT"
```

### Response `200`

```json theme={null}
[
  {
    "id":         "550e8400-e29b-41d4-a716-446655440000",
    "name":       "Production Key",
    "type":       "live",
    "key_prefix": "nmc_live_abc1...",
    "expires_at": null,
    "created_at": "2026-04-09T10:30:00.000Z"
  }
]
```

***

## Revoke an API key

```
DELETE /api/v1/api-keys/:id
```

Permanently revokes an API key. Any requests using the revoked key will immediately start receiving `401 Unauthorized`.

### Request

```bash theme={null}
curl -X DELETE https://api.numonic.com/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT"
```

### Response `200`

```json theme={null}
{
  "message": "API key revoked successfully"
}
```

### Errors

| Status | Code        | Cause                                       |
| ------ | ----------- | ------------------------------------------- |
| `404`  | `NOT_FOUND` | Key not found or belongs to another account |

***

## Key format

API keys follow this format:

```
nmc_[type]_[base64url-encoded-secret]
```

* `nmc_live_...` — live key, works against the production SES environment
* `nmc_test_...` — test key, for development (behavior may differ)

Use the `key_prefix` (e.g. `nmc_live_abc1...`) to identify which key is which in the dashboard without exposing the full secret.