Authentication and keys
Every call to the Ultimo API carries the service key of an integration. The integration decides what the key may do: its permissions, read only or read and change, and which agents it may use.
The Authorization header
Send the key as a Bearer token on every request:
curl
curl https://api.ultimo-bots.com/v1/agents \
-H "Authorization: Bearer $ULTIMO_API_KEY"A missing, unknown or revoked key answers 401 invalid_api_key. More than 30 failed attempts per minute from one address answer 429 too_many_failed_attempts for the rest of the minute.
Integrations and keys
An integration is one application that talks to your agents, for example “Intranet chat” or “Ticket system”. It belongs to the workspace and has its permissions, its access (read only, or read and change) and its agents (all, or the ones you choose). Keys are only the credentials of an integration:
- A key looks like
ub_live_followed by 40 characters and is shown once when you create it. - Ultimo stores only a hash of it. A lost key cannot be shown again: create a new one.
- A revoked key stops working at once. Revoking the integration stops all its keys and webhooks.
- Nothing depends on a person: a password change or a teammate leaving does not stop the integration.
- The API is part of the Ultimo plan, per agent.
GET /v1/agentsshows each agent withapi_access; calls for an agent on another plan answer403 plan_restricted.
Create an integration and a key
Open the API page
In the portal, open the agents overview and click API in the sidebar. The page is called API & Integrations.
Create the integration
Click + Integration, give it a name, pick a template or single permissions, choose read only or read and change, and the agents it may use.
Copy the key
The key is shown once. Store it in your server's secret store, for example as the environment variable
ULTIMO_API_KEY.
Rotate a key without downtime
An integration can hold up to five keys at once. To replace a key:
- Create a second key on the same integration with + Key.
- Deploy the new key to your servers.
- Revoke the old key. It stops working at once; the integration and its webhooks keep running.
Read only, or read and change
An integration with read only access can call every reading endpoint its permissions allow. Endpoints that change something (sending a message, adding knowledge, changing the widget, managing webhooks) also need read and change access; the reference marks them with “Needs an integration with read and change access”. Without it they answer 403 read_only_integration.
Permissions
Pick a template when you create the integration, or choose single permissions:
| Template | Permissions |
|---|---|
| Chat only | chat:write, agents:read |
| Chat and knowledge | plus knowledge:read, knowledge:write, webhooks:write |
| Full access | every permission, including all conversations, leads, insights, exports and AI credits |
An integration with chat:write reads only its own conversations; all conversations of an agent (website, WhatsApp, other integrations) need conversations:read_all. Each permission opens these endpoints:
| Permission | Endpoints |
|---|---|
chat:write | |
agents:read | |
agents:context:read | |
agents:context:write | |
agents:behaviors:read | |
widget:read | |
widget:write | |
knowledge:read | |
knowledge:write | |
conversations:read_all | |
livechat:read | |
leads:read | |
leads:write | |
exports:read | |
reports:read | |
credits:read | |
webhooks:write |
A call without the permission answers 403 insufficient_scope; a call for an agent the integration may not use answers 404 not_found, the same as an agent that does not exist.