Authentication

The Convot API authenticates with an API key. Each key belongs to one app and carries a specific set of permissions (scopes).

Create a key

1. In the dashboard, open the app you want to integrate with.
2. Go to App Settings → API Keys.
3. Click New key, give it a name, and choose the scopes it needs.
4. Copy the token shown. It looks like ck_xxxxxxxxxxxxxxxx:secret.

The full token is shown once, at creation. We store only a hashed version, so if you lose it you revoke the key and create a new one. Keys never expire on their own, but you can revoke any key instantly from the same screen.

Authenticate a request

Send the token as a Bearer token on every request:

curl https://app.convot.io/v1/conversations \
  -H "Authorization: Bearer ck_xxxxxxxxxxxxxxxx:secret"

A missing, malformed, or revoked key returns 401 Unauthorized.

Keep keys safe

• Treat the token like a password. Store it in an environment variable or a secrets manager, never in client-side code or a public repo.
• Use separate keys for separate systems (production backend, a script, a third-party tool) so you can revoke one without affecting the others.
• Grant the narrowest scopes a key actually needs. See Scopes and permissions.