Skip to main content
All API requests require a Bearer token in the Authorization header. 
curl https://api.open.cx/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Generate an API key

  1. Go to Settings → Access in the OpenCX dashboard.
  2. Click Create API Key.
  3. Give it a name (e.g. “Production”, “Staging”).
  4. Choose access level:
    • Full access — the key can call every endpoint with no restrictions.
    • Custom scopes — select only the resources and actions (read / write) this key needs.
  5. Copy the key.
Existing keys created before scopes were introduced remain full-access.
The full key is only shown once. Store it securely — if you lose it, generate a new one.

​
Using the key

Pass the key as a Bearer token in the Authorization header on every request: 
Authorization: Bearer ocx_live_abc123...

curl -X GET https://api.open.cx/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Scopes

Scopes restrict an API key to specific resources and actions. A full-access key bypasses all scope checks, while a scoped key can only call the endpoints it was granted. Each scope follows the pattern resource:action, where action is read (GET / list) or write (create / update / delete).

​
Available scopes

ResourceReadWrite
Actionsactions:readactions:write
Autopilotautopilot:readautopilot:write
Blocklistblocklist:readblocklist:write
Chat sessionschat-sessions:readchat-sessions:write
Contactscontacts:readcontacts:write
Crawlcrawl:readcrawl:write
CSATcsat:readcsat:write
Emailemail:reademail:write
Handoff analyticshandoff-analytics:read—
Help centerhelp-center:readhelp-center:write
Insightsinsights:readinsights:write
Office hoursoffice-hours:readoffice-hours:write
Organizationorg:readorg:write
Phonephone:readphone:write
Redactionredaction:readredaction:write
Sequencessequences:readsequences:write
SIPsip:readsip:write
Tagstags:readtags:write
Teamsteams:readteams:write
Trainingtraining:readtraining:write
WhatsAppwhatsapp:readwhatsapp:write
Widgetwidget:readwidget:write
Workflowsworkflows:readworkflows:write
Handoff analytics only supports read — there is no write scope.

​
Error responses

StatusMeaning
401 UnauthorizedMissing or invalid API key
403 ForbiddenKey is valid but lacks the required scope
401 — invalid or missing key 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}
403 — missing scope 
{
  "statusCode": 403,
  "message": "This API key does not have the required scope: \"tags:read\"."
}

​
Best practices

  • Never commit keys to source control. Use environment variables or a secrets manager.
  • Rotate keys periodically. You can create multiple keys and revoke old ones from the dashboard.
  • Use separate keys for each environment (production, staging, development) so revoking one doesn’t break the others.
  • Use scoped keys in production. Grant only the permissions each integration needs (principle of least privilege).
  • Prefer separate keys per integration so revoking one doesn’t break others, and each gets only the scopes it needs.