Authentication and scopes
Every request authenticates with a workspace API key sent as a bearer token:
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.
Creating keys
Section titled “Creating keys”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.
Testing credentials
Section titled “Testing credentials”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.
Scopes
Section titled “Scopes”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.
Rotating and revoking keys
Section titled “Rotating and revoking keys”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.