Authentication
The project key, scopes, the workspace boundary and why the API does not answer a browser.
On this page
The key #
Every request carries the Authorization: Bearer wck_… header. A key is issued for one connected site and opens the conversations of that site only: a neighbouring connection's conversation is not found with it even by an exact id.
The database keeps only the fingerprint of the key. A lost key is not recovered: it is revoked and issued again. A revoked key stops opening anything immediately — the record stays with a revokedAt mark.
Authorization: Bearer wck_cZLLSCqi7pQ2m4E1vN…The key is a server key. It must not go into your page code: any visitor would read it there and get access to every conversation of the site.
Scopes #
| Scope | Methods |
|---|---|
| conversations:read | GET /conversations, GET /conversations/{id}, GET /conversations/{id}/messages |
| conversations:write | POST /conversations/{id}/messages, POST /conversations/{id}/close |
| media:read | GET /media/{id} |
CORS #
The public API deliberately serves no CORS headers, so a request from a visitor's browser will not pass. The widget uses another entrance — a signed window token issued by the gateway.
Authentication failures #
| HTTP | code | When |
|---|---|---|
| 401 | unauthorized | no header, wrong key or a revoked one |
| 403 | insufficient_scope | the key has no scope for this method |
| 429 | rate_limit_exceeded | more than 300 requests per minute per key |