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

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:

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`

{
  "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"
}

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.

List API keys

GET /api/v1/api-keys

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

Request

curl https://api.numonic.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT"

Response `200`

[
  {
    "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

curl -X DELETE https://api.numonic.com/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT"

Response `200`

{
  "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.

Getting Started

API Reference

API Keys

API Keys

Create an API key

Request

Body parameters

Response `201`

List API keys

Request

Response `200`

Revoke an API key

Request

Response `200`

Errors

Key format

​API Keys

​Create an API key

​Request

​Body parameters

​Response 201

​List API keys

​Request

​Response 200

​Revoke an API key

​Request

​Response 200

​Errors

​Key format

API Keys

Create an API key

Request

Body parameters

Response `201`

List API keys

Request

Response `200`

Revoke an API key

Request

Response `200`

Errors

Key format