API authentication and common responses

All management methods use one bearer token:

Authorization: Bearer CLIENT_ID.CLIENT_SECRET

CLIENT_ID identifies an active Dzen Chat API client. CLIENT_SECRET is the secret issued for that client. Concatenate them with one period, keep the complete value on the server that calls the API, and never expose it in browser JavaScript, a public repository, a URL, or a log.

curl 'https://chat.example.com/api/pages?limit=20' \
  -H 'Authorization: Bearer CLIENT_ID.CLIENT_SECRET'

The token determines the project and, for pages and sources, the sources that the client may access. A request never supplies project_id to choose its own scope.

JSON requests

Methods that create or change data accept JSON. Send both headers:

Authorization: Bearer CLIENT_ID.CLIENT_SECRET
Content-Type: application/json

For example:

curl -X POST 'https://chat.example.com/api/widgets' \
  -H 'Authorization: Bearer CLIENT_ID.CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Support assistant"}'

Error format

Errors are JSON objects with an error string:

{
  "error": "invalid bearer token"
}

Status	Meaning
401	The bearer token is missing, malformed, inactive, or unknown.
404	The requested resource does not exist in the client’s permitted project or source set.
403	The URL passed to POST /api/update is outside the client’s assigned sources.
422	The JSON body, path parameter, or query parameter does not satisfy the documented type or limit.

Collection responses use an items array. Timestamps are ISO 8601 strings. The public widget trigger endpoint is an exception: it is called from the visitor’s browser and is documented under Widgets.