Authentication and scopes
Every request carries an API key, and each key holds only the scopes you give it.
API keys
Send the key as a bearer token. It reads omn_ followed by 43 characters and belongs to one organisation, so a request needs nothing else to say which one.
curl https://api.omnio.sawego.com/v1/contacts \
-H "Authorization: Bearer $OMNIO_API_KEY"
Owners and admins create and revoke keys in Settings, API keys. Omnio keeps only a SHA-256 of the key and shows it once. Revoking takes effect on the next request. A key cannot create keys or manage webhook endpoints.
Scopes
Each route in the reference names the scope it needs. Give a key the fewest that do the job.
| Scope | Allows |
|---|---|
messages:read | Read messages and download their files |
messages:write | Send messages and reactions, and upload files |
conversations:read | List and read conversations, notes and activity |
conversations:write | Change status and assignee, add notes |
contacts:read | Read contacts, tags, stages and custom fields |
contacts:write | Create, change, tag, block and delete contacts |
crm:admin | Manage tags, lifecycle stages and custom fields |
content:read | Read templates and snippets |
imports:write | Import contacts and manage mappings |
settings:read | Read the organisation, members, teams and channels |
settings:write | No public route uses it yet |
Search takes contacts:read, messages:read or both, and returns the groups the key may read.
When a key is refused
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | The key is unknown or revoked, or the header is missing |
| 403 | insufficient_scope | The key lacks the scope this route needs |