Skip to Content
Baseera Docs

User tokens and publishable keys

The threat model for Baseera's keys and tokens, what a leak allows, and how to rotate.

Four credentials are involved: a publishable key, a secret key, user tokens and server tokens. See Authentication for how they are sent. This page covers why they are built the way they are.

Design

Secret keys are Ed25519 seeds, not HMAC secrets. A secret key is sk_ plus a random 32-byte seed. The platform's server generates it and shows it once. The database stores only its SHA-256 hash and the public key. With HMAC, whoever can verify can also forge. Here, public keys only verify, so a full database leak can neither forge a token nor reveal a key.

Only EdDSA is accepted. none and the HS*, RS* and ES* algorithms are refused before any key is read. That rules out algorithm confusion, including HS256 signed with the public key as the HMAC secret. There is a test for that case.

Lifetimes are short. User tokens last 15 minutes by default and at most 1 hour, with 30 seconds of clock skew. Server tokens last at most 60 seconds. A tenant upload token lasts at most 10 minutes, and is bound to one tenant, knowledge base and user.

A server token has one purpose. A finish token cannot push knowledge, and the reverse. A server token is never accepted as a user token, so it can never open a session.

Publishable keys are public on purpose. A pk_ key identifies the agent and works only from the agent's allowed domains. It is meant for the browser, so secrecy adds nothing. The origin allow-list is the control.

What a leak allows

LeakedWhat an attacker can doWhat they cannot do
Publishable keyRead the agent's public theme and logo from an allowed origin. A request from another origin is refused.Open a session as a user, read knowledge, or call a server endpoint.
User tokenAct as that one user and tenant until it expires, at most 1 hour.Act as another user or tenant, or call a server endpoint.
Server tokenMake one kind of call for at most 60 seconds.Do anything else, or open a session.
Secret keySign tokens for that agent, which can open sessions as any user and call server endpoints.Read another agent's data. The key reaches only its own agent.
Database contentsLearn public keys and hashes.Forge a token or recover a key.

A secret key leak is serious. Revoke it at once.

Dev mode

An agent can allow sessions without a user token only when the request's Origin is localhost or 127.0.0.1. It is off by default. Do not leave it on for a production agent.

Allowed domains

A request without an Origin is refused. Successful responses allow only the agent's allowed domains. Error responses allow any origin so the SDK can show the developer why. Cookies are never used for the runtime API, and credentials are never allowed, so a CORS mistake cannot be turned into a cross-site request carrying someone's session.

Rotation

Secret keys can be rotated without downtime:

Create a new secret key

In the console, create a second secret key for the agent. It is shown once. Creating a key needs a second factor when your organization requires one.

Deploy it

Put the new key in your server's environment and deploy. Tokens now carry the new key's kid. The runtime finds the matching public key by kid, so old and new keys work side by side.

Revoke the old key

Revoke the old key in the console. A revoked key stops working at once, and tokens it signed fail on their next request.

Because user tokens are short-lived, nobody is signed out for long: the SDK asks your getUserToken() for a new one before expiry.

To rotate a publishable key, create a new one, update your front end, then revoke the old one. A revoked key answers invalid_key.

To rotate a webhook signing secret, save the endpoint again in the console. That makes a new whsec_ secret, shown once. The signature header can carry several v1 values during a rotation, and the verifier accepts a match on any.

Your responsibilities

  • Authorize the user on your own server before signing a token. Baseera trusts the claims you sign.
  • Keep sk_ keys out of browser code, repositories and logs. Baseera redacts key shapes in its own logs, and CI scans for committed secrets.
  • Keep ttlSeconds short if you need fast cut-off of a user.
  • Never sign a token with a purpose claim for a browser.

Next steps

On this page