API authentication

The Vicero REST API is served under /v1. Everything is JSON, and every request must be authenticated.

Authentication

Vicero API requests require an API key. Send it with every request in the Authorization header:

Authorization: Bearer YOUR_API_KEY

YOUR_API_KEY is a placeholder used throughout this documentation. Replace it with a key from your own workspace. This page never shows a real key and never fills one in for you.

An API key identifies your workspace to the API, so requests are made inside your organization and you do not need to say which one you mean. You create and manage keys in the dashboard, under Settings → API Keys — that is the only place a key is created, shown, rotated or revoked.

Manage API keys

How authentication works

Create a key in Settings → API Keys and store it somewhere safe. A key is shown when it is created, so copy it then.
Send it as a bearer token in the Authorization header of every request.
Vicero checks the key and runs the request as your workspace.
A missing, wrong or revoked key is refused with a 401 and a typed error — see Errors.

Always call the API over HTTPS. A request over plain HTTP exposes the key to anyone on the path.

Example request

List your agents:

curl https://YOUR_API_HOST/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch("https://YOUR_API_HOST/v1/agents", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const agents = await response.json();

import requests

response = requests.get(
    "https://YOUR_API_HOST/v1/agents",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
agents = response.json()

The copy button copies the example exactly as shown, placeholder included. Replace YOUR_API_KEY yourself — ideally by reading it from an environment variable rather than typing it into the code.

Security recommendations

Keep it on the server. Anything that runs in a browser or a mobile app can be inspected; call Vicero from your backend instead.
Never put it in a URL. URLs end up in logs, browser history and proxy caches.
Use a separate key for each environment, so a leak in one does not touch the others.
Revoke a key the moment you suspect it has leaked, from Settings → API Keys, and create a new one.

Manage API keys

Other ways to authenticate

Signing in as a person. The dashboard and the widget authenticate people rather than servers. Signing in returns a short-lived access token and a refresh token:

curl -X POST https://YOUR_API_HOST/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"me@acme.com","password":"…"}'

Send the access token as Authorization: Bearer <access_token> together with an X-Org-Id header naming the organization. The access token expires after about fifteen minutes; exchange the refresh token at POST /v1/auth/refresh for a new pair. Refresh tokens rotate: each exchange invalidates the one you used, so always store the new one.

The widget. It talks to /v1/public/agents/{public_key}/… with no credential at all. The public key in the path identifies one published agent's public chat and grants nothing else.

Errors — the response envelope and what the codes mean.
Streaming — SSE and WebSocket events.
Rate limits.
Endpoint reference — the customer-facing routes, generated from the API itself.