API authentication, responses and errors

Send the key in a header

Use one of these headers for authenticated requests:

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

The API also accepts ?api_key=, but prefer headers to keep secrets out of URLs and access history. Store keys server-side and replace any key that is exposed.

Permissions and key types

Scope	Use
`read`	Read resources covered by the API.
`write`	Read and write resources; includes read access.
`jobs:read`	Read job listings.
`jobs:write`	Create/update jobs through POST and unpublish jobs.
`spaces:read`	Read space endpoints.
`cities:read`	Read city lookups; broad `read` also covers this.
`events:read`	Read event endpoints.

cwk_rstr_ keys are read-only; cwk_live_ keys allow the configured write permissions. A prefix is not a permission grant by itself. The key’s configured scopes and space restrictions still apply. A job-write scope alone does not grant every read scope; choose the permissions needed for both setup and writing.

Response format

Success responses contain success, status and data. The shape of data depends on the endpoint: jobs use data.jobs, while cities and spaces return arrays.

{
  "success": false,
  "status": 422,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": ["Job title is required"]
  }
}

error.details is not always an array. For rate limits and permission errors it can be an object. Check its type before iterating. Handle network errors and non-JSON responses as well as API errors.

Fix common errors

HTTP status	Action
`400`	Check JSON syntax and the request format.
`401`	Check the key, expiry, revoked status and any IP restrictions.
`403`	Check the required scope and whether the job belongs to the key’s space.
`404`	Check the endpoint or resource identifier.
`405`	Use the endpoint’s supported HTTP method.
`409`	An idempotent request may still be processing; retry after a short delay.
`422`	Correct the fields listed in `error.details`.
`429`	Wait for `error.details.retry_after_seconds`, then retry with backoff and jitter.
`500`	Retry cautiously; include context in a support report without sharing secrets.

Job write operations are rate-limited per key. The reference gives a fallback of 120 writes per minute, but a key’s configured limit takes precedence. Use the returned limit and retry delay rather than assuming a quota.

For retries of job creation, reuse an Idempotency-Key for the same logical request. The reference documents successful response replay for 24 hours. Use a new key for a different operation. See Jobs API for a complete example.