Authentication

Every call carries an API key. A key belongs to one agent in one workspace, and it can do exactly what that agent may do.

Create a key

1. Open Settings → Agents in Olamma. You need to be a workspace owner or admin.
2. Add an agent and name it after what it does, like “Orders sync”. Choose an owner, the person responsible for it. If the owner leaves the workspace, its keys stop working.
3. Choose its access for each app (see below), and optionally a daily write limit and an end date.
4. Copy the key. It starts with oak_ and is shown once. Olamma keeps only a fingerprint of it.

Access levels

A key never gets more than its agent: the agent’s role in the workspace, its project access, its daily write limit and its end date all still apply. If the agent is turned off, expires, or its owner leaves the workspace, its keys stop working.

Send the key

Put it in the Authorization header of every call:

curl "https://api.olamma.sh/v1/w/your-workspace/me" \
  -H "Authorization: Bearer $OLAMMA_KEY"

const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/me`, {
  headers: {
    Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
  },
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

import os
import requests

response = requests.get(
    "https://api.olamma.sh/v1/w/your-workspace/me",
    headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}"},
    timeout=30,
)
data = response.json()
response.raise_for_status()

The key also decides the workspace: a key from one workspace can’t open another, even if you change the address.

Keep keys safe

• Store keys in your server’s environment or secret manager, never in source code.
• Each agent can have two working keys at once, so you can replace one without downtime: create the new key, deploy it, then revoke the old one.
• Revoke a key in Settings → Agents if it may have leaked. It stops working on its very next call.

When a key is refused