API Authentication

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.

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>:write

Every 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.

A restricted key can access only operations covered by its configured scopes.

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:

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:

Use the correlationId, when present, when contacting Convor support. Do not log API keys or include them in error reports.

Rotation checklist

1. Create a replacement key with the same or narrower scopes.
2. Deploy the replacement to the consuming service through its secret store.
3. Verify successful requests with the replacement key.
4. Revoke the old key.
5. Review logs for unexpected use of the revoked key.