API Authentication
Authenticate server-to-server requests with an organization API key and restrict each integration with resource read/write scopes.
The customer REST API uses organization API keys. Send requests to
https://api.convor.io; every documented endpoint path already includes the
/api prefix.
Create a separate key for each backend integration so you can restrict, rotate, and revoke one integration without affecting the others.
Keep secret keys on your server
Never place a convor_sk_… key in browser JavaScript, mobile application code,
a public repository, or an embedded widget. Route browser requests through your
own authenticated backend.
Send the API key
Convor accepts either of these equivalent forms. Use one form per request.
Bearer authorization
curl --request GET \
'https://api.convor.io/api/conversations' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer convor_sk_...'X-API-Key header
curl --request GET \
'https://api.convor.io/api/conversations' \
--header 'Accept: application/json' \
--header 'X-API-Key: convor_sk_...'Header names are case-insensitive, but examples and generated code use
X-API-Key for readability.
Scope model
A restricted API key uses scopes in the form:
<resource>:read
<resource>:writeEvery public endpoint has one exact required scope. GET and HEAD operations
normally use read; mutating operations normally use write. Treat the scope
shown on the endpoint page as authoritative instead of deriving it from the URL
in client code.
| Request | Required scope |
|---|---|
GET /api/conversations | conversations:read |
GET /api/conversations/{id} | conversations:read |
PATCH /api/conversations/{id} | conversations:write |
GET /api/operator-teams | operator-teams:read |
POST /api/operator-teams | operator-teams:write |
A restricted key can access only operations covered by its configured scopes.
Empty scope sets grant full API access
A key created with no scopes is unrestricted. Prefer the smallest explicit scope set required by the integration.
Product entitlement
Organization API requests require the automation_api integration module. A
valid key without that module returns HTTP 402 with code
INTEGRATION_MODULE_REQUIRED and structured details identifying
automation_api and public_api.
Authentication boundaries
Do not interchange the following credentials:
| Credential | Purpose | Valid for customer REST endpoints? |
|---|---|---|
Organization API key (convor_sk_…) | Server-to-server automation | Yes |
| Dashboard session cookie | First-party operator dashboard | No public integration contract |
Public widget key (convor_wpk_…) | Widget configuration and visitor bootstrap | No |
| Visitor bearer token | Visitor-scoped widget requests and realtime | No organization automation access |
| Webhook signing secret | Verify outbound webhook deliveries | No |
A public widget key is intentionally present in the embed snippet. It is not a secret API key and cannot authorize organization REST operations.
Authentication errors
Authentication and authorization failures use the standard error envelope:
{
"error": {
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action.",
"correlationId": "01J..."
}
}Common outcomes:
| Status | Meaning |
|---|---|
401 | The API key is missing, invalid, inactive, or cannot be authenticated. |
402 | The organization does not have the required API integration module. |
403 | The key lacks the required scope, the organization is unavailable, or another authorization boundary rejected the request. |
Use the correlationId, when present, when contacting Convor support. Do not log
API keys or include them in error reports.
Rotation checklist
- Create a replacement key with the same or narrower scopes.
- Deploy the replacement to the consuming service through its secret store.
- Verify successful requests with the replacement key.
- Revoke the old key.
- Review logs for unexpected use of the revoked key.
Czy ta strona była pomocna?