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.

3 min read Updated

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/agents shows each agent with api_access; calls for an agent on another plan answer 403 plan_restricted.
Server to server only. Never put a key into a website, a browser extension or a mobile app. For the browser there is the website widget.

Create an integration and a key

  1. Open the API page

    In the portal, open the agents overview and click API in the sidebar. The page is called API & Integrations.

  2. 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.

  3. 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:

  1. Create a second key on the same integration with + Key.
  2. Deploy the new key to your servers.
  3. 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:

TemplatePermissions
Chat onlychat:write, agents:read
Chat and knowledgeplus knowledge:read, knowledge:write, webhooks:write
Full accessevery 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:

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.

Next steps