Skip to main content
All Public API requests require an API key in the cx-api-key HTTP header:
Requests without a valid key receive 401 with code API_KEY_REQUIRED or INVALID_API_KEY.

​
Create and manage keys

Create keys in Settings → API. Each key is scoped to one organization — you cannot access another workspace’s data with the same key.
Name keys by purpose (prod-warehouse-sync, staging-ai-agent) so you know which integration to update during rotation.

​
Scopes

Scopes limit what a key can do. New keys default to tickets:read only. A key missing the required scope receives 403 with code FORBIDDEN_SCOPE.

​
Least privilege for AI agents

For read-only agent tools that list tickets, read threads, and summarize conversations:
  1. Create a key with only tickets:read.
  2. Do not grant tickets:write or tickets:export unless the agent must call legacy write/export endpoints.
  3. Link the key to a specific agent when you want view access to match that agent’s inbox permissions (see below).

​
Legacy keys without scopes

Keys created before scopes shipped may have an empty scopes column. Those keys retain full access during the migration window. Re-create keys with explicit scopes when you rotate.

​
Agent-linked keys and view access

When an API key is linked to a support agent:
  • GET /views returns only views that agent can see in the inbox.
  • GET /tickets?view_id=... returns 404 VIEW_NOT_FOUND if the view is not accessible to that agent.
Service keys with no linked agent see all organization views.
If your agent integration cannot find a view that exists in the UI, check whether the API key is agent-linked and whether that agent has access to the view’s sharing rules.

​
Security practices

  • Never expose API keys in client-side code, public repos, or browser extensions.
  • Rotate keys immediately if one is leaked.
  • Use separate keys per environment (staging vs production).
  • Prefer scoped keys over legacy full-access keys.