Skip to content

Authentication and scopes

Every request authenticates with a workspace API key sent as a bearer token:

Terminal window
curl https://optlo.com/api/v1/me \
-H "Authorization: Bearer YOUR_API_KEY"

Keys have the form optlo_live_<keyId>_<secret>. Each key belongs to one workspace, and every request acts on that workspace.

Workspace admins create keys in Settings → API keys. The full key is shown once, when it is created. Store it in a secret manager or environment variable, never in client-side code or a repository.

Give each integration its own key with only the scopes it needs. Separate keys can be rotated or revoked without affecting other integrations, and events record which key performed each action.

GET /api/v1/me works with any valid key, including a key without scopes. It returns the workspace and the key’s ID, name, and scopes:

{
"workspace": { "id": "ws_…", "name": "Acme" },
"key": { "id": "key_…", "name": "CRM sync", "scopes": ["users:read", "users:write"] }
}

A missing, malformed, revoked, or expired key returns 401 invalid_credentials.

Each operation in the REST reference lists the scope it requires. A key without that scope receives 403 permission_denied.

Scope Grants
users:read List and get users; user.email_captured events
users:write Create and update users
conversations:read List and get conversations; conversation events
conversations:write Create, close, and reopen conversations
messages:read Read customer-visible messages; message.created events
messages:write Send messages as an operator
notes:read Read internal notes; note.created events
notes:write Add internal notes
assistants:read List and get assistants
assistants:write Send messages as an assistant
operators:read List and get operators
organizations:read List and get organizations
webhooks:manage Create, list, and delete webhooks, and view delivery history

Write scopes do not imply read scopes. An integration that creates users and then looks them up needs both users:write and users:read. Write responses return the created or updated resource without the read scope.

Some operations need more than one scope. Creating a conversation requires conversations:write plus messages:write for an operator sender, or assistants:write for an assistant sender. Creating a webhook requires webhooks:manage plus the read scope for every event type it subscribes to.

Event visibility follows read scopes. A key sees only the events its read scopes allow.

Rotate a key in Settings → API keys to replace its secret. The replacement keeps the name and scopes, and the existing key remains active for up to two hours so you can deploy the new value without downtime.

Revoke a key to stop it working immediately. Revocation cannot be undone; create a new key if the integration is needed again.

Idempotency keys are scoped to the API key that sent the request. After rotation, a retry sent with the new key starts a separate operation. See Idempotent requests.