Skip to main content

​
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

ParameterTypeRequiredDescription
namestringYesA label for this key (e.g. “Production”, “Staging”)
typestringYeslive for production sending, test for development
expires_atstringNoISO 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

StatusCodeCause
404NOT_FOUNDKey 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.