API Keys

Create, list, and revoke API keys programmatically.

List API Keys

GET /api/v1/keys

Required scope: keys:manage

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Production Integration",
      "prefix": "msk_...",
      "scopes": ["send", "contacts:read"],
      "last_used_at": "2026-04-13T08:42:00Z",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Note: Full key values are never returned after creation — only the prefix is shown for identification.

Create an API Key

POST /api/v1/keys

Required scope: keys:manage

Request Body

{
  "name": "Shopify Integration",
  "scopes": ["send", "contacts:write"]
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Human-readable label for the key | | scopes | string[] | Yes | Array of permission scopes |

Available Scopes

| Scope | Description | |-------|-------------| | send | Send emails and messages | | contacts:read | Read contacts and lists | | contacts:write | Create, update, delete contacts | | campaigns:read | Read campaigns | | campaigns:write | Create, update, send campaigns | | templates:read | Read templates | | templates:write | Create, update templates | | analytics:read | Read analytics | | keys:manage | Create and revoke API keys |

Response

201 Created

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Shopify Integration",
    "key": "msk_SHOWN_ONCE_STORE_IMMEDIATELY",
    "scopes": ["send", "contacts:write"],
    "created_at": "2026-04-14T10:00:00Z"
  }
}

The full key is only returned once at creation. Store it securely — it cannot be retrieved again.

Revoke an API Key

DELETE /api/v1/keys/:id

Required scope: keys:manage

Immediately invalidates the key. Any integrations using it will start receiving 401 errors.

Response

200 OK

{ "success": true }

Errors

| Status | Code | Description | |--------|------|-------------| | 400 | VALIDATION_ERROR | Invalid scopes or missing name | | 401 | UNAUTHORIZED | Invalid or missing API key | | 403 | FORBIDDEN | Key lacks keys:manage scope | | 404 | NOT_FOUND | Key not found |