API Keys

API keys provide programmatic access to CampaignOS APIs, scoped to a workspace.

List API Keys

GET /api/workspaces/{workspaceId}/keys

Returns all API keys with masked values.

Auth: Session + ADMIN role required

Response:

[
  {
    "id": "key_abc123",
    "name": "Production API",
    "key": "cos_xxxxxxxx...xxxx",
    "scopes": ["contacts.read", "contacts.write", "campaigns.read"],
    "expiresAt": "2027-01-15T00:00:00.000Z",
    "lastUsedAt": "2026-01-14T15:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
]

Keys are partially masked — the full key value is only returned at creation time.

Create API Key

POST /api/workspaces/{workspaceId}/keys

Auth: Session + ADMIN role required

Request Body:

{
  "name": "Production API",
  "scopes": ["contacts.read", "contacts.write", "campaigns.read"],
  "expiresAt": "2027-01-15T00:00:00.000Z"
}

Response (201): API key object with full key value (shown only once).

{
  "id": "key_abc123",
  "name": "Production API",
  "key": "cos_0123456789abcdef0123456789abcdef0123456789abcdef",
  "scopes": ["contacts.read", "contacts.write", "campaigns.read"],
  "expiresAt": "2027-01-15T00:00:00.000Z"
}

Important: Save the key immediately — it cannot be retrieved again.

Revoke API Key

DELETE /api/workspaces/{workspaceId}/keys/{keyId}

Revokes an API key. Keys can also be revoked from Settings → API Keys.

Auth: Session + ADMIN role required

Scopes

Scope values are the same permission names used for workspace roles. A key with an empty scopes array (or "*") is granted every permission.

Using API Keys

Keys are prefixed with cos_ and must be sent in the Authorization header as a Bearer token. Query-string authentication is not supported.

Authorization: Bearer cos_0123456789abcdef0123456789abcdef0123456789abcdef