Guide

Authenticate API requests

Public API calls use bearer API-key authentication. Make requests from your server and keep keys out of browsers, mobile apps, public repositories, and logs.

Required header

Authorization: Bearer <API_KEY>

Requests without a bearer token return 401 authentication_required. Authenticated requests are authorized against the key scopes and the workspace selected for the request.

Workspace scoping

If an API key can access more than one workspace, include X-Workspace-Id. You may also send X-Organization-Id as a guardrail; if it does not match the authenticated key context, the API returns organization_context_mismatch.

curl "https://api.ctct.dev/v1/me" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Workspace-Id: <WORKSPACE_ID>"

Safe key handling

Store API keys in server-side secret storage or environment variables.
Use the narrowest scopes your integration needs.
Rotate keys when team access changes or when a key may have been exposed.
Never embed API keys in frontend JavaScript.

Common auth errors

401 authentication_required — Missing or invalid Authorization: Bearer <API_KEY>.

403 permission_denied — The key authenticated, but does not have the required scope or authorization for this workspace.

403 organization_context_mismatch — The supplied organization header does not match the authenticated organization.