Skip to Content
Baseera Docs

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

CredentialFormatWhere it livesWhat it does
Publishable keypk_ plus 48 hex charactersBrowser, publicIdentifies the agent. Only works from the agent's allowed domains.
Secret keysk_ plus 64 hex charactersYour server onlySigns user tokens and server tokens. Never sent to Baseera.
User tokenEdDSA JWTBrowser, short-livedSays which user and tenant are in the session.
Server tokenEdDSA JWT with a purposeServer to server, 60 secondsAuthorizes one kind of server call.
Agent iduuidYour serverSent 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:

HeaderValueRequired
x-baseera-keyPublishable keyYes
x-baseera-user-tokenUser token from your serverYes, except in dev mode from localhost
x-baseera-protocolv0No
OriginSet 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:

HeaderValue
x-baseera-agentThe agent's id (uuid)
x-baseera-server-tokenA 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:

PurposeEndpoint
kb_writePush, read status of and delete knowledge items, reserve uploads
purge_knowledgeDELETE /v0/knowledge/tenants/{tenantId}
verify_finishPOST /v0/finish/verify
eval_runPOST /v0/evals/runs, GET /v0/evals/runs/{id}
signalPOST /v0/signals
kb_tenant_uploadTenant 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.

server.ts
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 familyPublishable keyOriginUser tokenServer token
Sessions, turns, tool results, feedback, finish, trail, AI checks, source linksYesYesYesNo
Agent theme and logoYesYesNoNo
Knowledge push, status, delete, uploadsNoNoNokb_write
Tenant purgeNoNoNopurge_knowledge
Finish verifyNoNoNoverify_finish
SignalsNoNoNosignal
Eval runsNoNoNoeval_run
Tenant uploadsYesYesNokb_tenant_upload in x-baseera-upload-token

Failures

CodeStatusCause
invalid_key401Publishable key unknown or revoked
origin_not_allowed403Origin is not in the agent's allowed domains
invalid_user_token401Missing, malformed, wrong key, wrong algorithm, wrong agent, or a server token
user_token_expired401A correctly signed token that has expired
invalid_server_token401Missing, malformed, wrong agent or purpose, or valid for more than 60 seconds

Next steps

On this page