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", "events:write"],
    "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", "events:write"],
  "expiresAt": "2027-01-15T00:00:00.000Z"
}

Field	Type	Required	Description
`name`	string	Yes	Display name for the key
`scopes`	string[]	Yes	Permission scopes
`expiresAt`	string	No	Expiration date (ISO 8601)

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


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

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

Delete API Key

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

Revokes an API key.

Auth: Session + ADMIN role required

Request Body:


{
  "keyId": "key_abc123"
}

Using API Keys

Include the key in the Authorization header:


Authorization: Bearer cos_live_abcdef1234567890abcdef1234567890

Or pass it as a query parameter for simple integrations:


GET /api/workspaces/{workspaceId}/contacts?key=cos_live_abcdef...