Getting started · 04

Authentication.

Every request to the Olbrain API is authenticated by an Access Key — an ak_* token your backend sends as a Bearer token. The exceptions are signed webhooks, where a signature replaces the key, and website chat, which is locked to your sites instead.

The Access Key

An Access Key is a token prefixed with ak_. It belongs to one organization and carries a set of permissions; for calling agents the relevant one is agents:invoke. A key can also be limited to a single agent.

Formattoken
ak_a1b2c3d4e5f6...

Send the key on every request as a Bearer token:

HeaderHTTP
Authorization: Bearer ak_<your-key>

Minting a key

From Noesis

In Noesis, open Settings → Organization → Access keys, click Create key, name it, and copy the token shown. When Alchemist hands over a new agent, its finish page can create a key limited to that agent.

From the API

Mint a keycURL
POST https://studio.olbrain.com/api/v1/organizations/<org_id>/access-keys
Authorization: Bearer <your-user-token>
Content-Type: application/json

{
  "name": "webhook key — shopify production",
  "permissions": ["agents:invoke"]
}

The response contains the raw key once. Store it in a secrets manager — it cannot be retrieved again. Keep it on your server: it can call, and bill, your agents, so it never goes in browser code.

Scope & access

An organization key can call any agent in its organization. A key limited to one agent can call only that agent. Calling an agent in another organization, or another agent with a limited key, comes back as 404 agent_not_found — the same answer as an agent that doesn't exist.

Revoking a key

In Noesis, open Access keys, find the key, click Revoke. The next webhook request signed with that key is rejected with 401 within about 30 seconds.

Best practices