Authentication
Which credential goes with which endpoint: publishable key, secret key, user token and server token.
Baseera has two key types and two token types. Browser calls use a publishable key and a user token. Server calls use a secret key to sign a short-lived server token.
Credentials
| Credential | Format | Where it lives | What it does |
|---|---|---|---|
| Publishable key | pk_ plus 48 hex characters | Browser, public | Identifies the agent. Only works from the agent's allowed domains. |
| Secret key | sk_ plus 64 hex characters | Your server only | Signs user tokens and server tokens. Never sent to Baseera. |
| User token | EdDSA JWT | Browser, short-lived | Says which user and tenant are in the session. |
| Server token | EdDSA JWT with a purpose | Server to server, 60 seconds | Authorizes one kind of server call. |
| Agent id | uuid | Your server | Sent with a server token so the runtime knows which agent's keys to check. |
A secret key is shown once, when you create it in the console. Baseera stores only a hash and the public key, so it cannot show it again. Put it in a server environment variable and never in browser code.
Browser requests
Every browser request carries these headers:
| Header | Value | Required |
|---|---|---|
x-baseera-key | Publishable key | Yes |
x-baseera-user-token | User token from your server | Yes, except in dev mode from localhost |
x-baseera-protocol | v0 | No |
Origin | Set by the browser. Must be one of the agent's allowed domains. | Yes. A request without one is refused. |
The runtime checks the key, then the origin, then the user token, on every request, not only when a session starts.
curl -X POST "$BASEERA_URL/v0/sessions" \
-H "Origin: https://app.example.com" \
-H "x-baseera-key: pk_0123456789abcdef0123456789abcdef0123456789abcdef" \
-H "x-baseera-user-token: $USER_TOKEN" \
-H "content-type: application/json" \
-d '{ "locale": "ar" }'The browser sets Origin for you. In curl you set it yourself, and it must match an allowed domain or the call fails with origin_not_allowed.
Dev mode
An agent can allow sessions without a user token. The runtime accepts that only when the request's Origin is localhost or 127.0.0.1. It is off by default. Use it for a first run, not for production.
Server requests
Server-to-server endpoints carry no publishable key and no Origin. They use two headers instead:
| Header | Value |
|---|---|
x-baseera-agent | The agent's id (uuid) |
x-baseera-server-token | A JWT signed by one of the agent's secret keys |
A server token has sub: "server", aud set to the agent id, a purpose, and a lifetime of at most 60 seconds. The purpose limits what the token can do:
| Purpose | Endpoint |
|---|---|
kb_write | Push, read status of and delete knowledge items, reserve uploads |
purge_knowledge | DELETE /v0/knowledge/tenants/{tenantId} |
verify_finish | POST /v0/finish/verify |
eval_run | POST /v0/evals/runs, GET /v0/evals/runs/{id} |
signal | POST /v0/signals |
kb_tenant_upload | Tenant uploads from the browser. Lives up to 10 minutes and is bound to a tenant, knowledge base and user. |
A token for one purpose cannot call another purpose's endpoint, and a server token can never open a user session.
Sign a server token with signServerToken from @baseera/core, or let @baseera/node do it. createBaseera signs a fresh token for each call.
import { signServerToken, HEADERS } from "@baseera/core";
const token = await signServerToken(process.env.BASEERA_SECRET_KEY!, {
agentId: process.env.BASEERA_AGENT_ID!,
purpose: "kb_write",
});
const response = await fetch(`${process.env.BASEERA_URL}/v0/knowledge/${kbId}/items/refund-policy`, {
headers: {
[HEADERS.agent]: process.env.BASEERA_AGENT_ID!,
[HEADERS.serverToken]: token,
},
});Because a server token has a 60-second life and one purpose, a replayed token has a short window and little reach.
Which endpoint takes what
| Endpoint family | Publishable key | Origin | User token | Server token |
|---|---|---|---|---|
| Sessions, turns, tool results, feedback, finish, trail, AI checks, source links | Yes | Yes | Yes | No |
| Agent theme and logo | Yes | Yes | No | No |
| Knowledge push, status, delete, uploads | No | No | No | kb_write |
| Tenant purge | No | No | No | purge_knowledge |
| Finish verify | No | No | No | verify_finish |
| Signals | No | No | No | signal |
| Eval runs | No | No | No | eval_run |
| Tenant uploads | Yes | Yes | No | kb_tenant_upload in x-baseera-upload-token |
Failures
| Code | Status | Cause |
|---|---|---|
invalid_key | 401 | Publishable key unknown or revoked |
origin_not_allowed | 403 | Origin is not in the agent's allowed domains |
invalid_user_token | 401 | Missing, malformed, wrong key, wrong algorithm, wrong agent, or a server token |
user_token_expired | 401 | A correctly signed token that has expired |
invalid_server_token | 401 | Missing, malformed, wrong agent or purpose, or valid for more than 60 seconds |