Skip to Content
Baseera Docs

User tokens

The EdDSA token your server signs to tell Baseera which user and tenant are in a session.

A user token tells Baseera who the person is and which of your customers (tenant) they belong to. Your server signs it with a secret key and hands it to the browser. The browser sends it in the x-baseera-user-token header on every request.

{ "alg": "EdDSA", "typ": "JWT", "kid": "9f2c4e7a1b3d5f60" }
  • alg must be EdDSA. none and every HS*, RS* and ES* algorithm are refused before any key is read. That also rules out the attack of signing with HMAC using the public key as the secret.
  • kid is the first 16 hex characters of the public key that matches your secret key. It picks the right key after a rotation.

Claims

Prop

Type

Nothing else is stored. Names and roles are not kept on the session; the session records the user id, tenant id and locale.

Claim names match ^[A-Za-z0-9_.-]{1,64}$. A token whose claims do not fit the limits is refused with invalid_user_token. The runtime never repairs it, because silently dropping a claim could widen or narrow access without anyone noticing.

A token with a purpose claim, or with sub: "server", is a server token and is refused here. A server token can never open a session.

Lifetime

The default lifetime is 15 minutes and the maximum is 1 hour. The runtime allows 30 seconds of clock skew. The SDK calls your getUserToken() again before the token expires.

An expired token fails with user_token_expired (HTTP 401). A token that is malformed, badly signed, for another agent or of the wrong kind fails with invalid_user_token.

Sign a token

Sign on your server with signUserToken from @baseera/node, using the agent's secret key:

app/api/baseera-token/route.ts
import { signUserToken } from "@baseera/node";

export async function POST() {
  const user = await requireUser(); // your own auth

  const token = await signUserToken(
    {
      userId: user.id,
      tenantId: user.organizationId,
      name: user.name,
      locale: "ar",
      role: "accountant",
      claims: { plan: "pro", groups: ["finance"] },
    },
    process.env.BASEERA_SECRET_KEY!, // sk_..., server only
    { ttlSeconds: 900 },
  );

  return Response.json({ token });
}

Options: ttlSeconds (1 to 3600, default 900) and agentId (adds aud).

signUserToken throws if the secret key is not an sk_ key, if a field is over its limit, or if claims do not fit. A publishable key cannot sign tokens.

Authorize the user on your own server before signing. Baseera trusts the claims you sign. If you sign a token for someone who should not have access, Baseera cannot tell.

How the runtime verifies a token

  1. The runtime reads the header and refuses anything but EdDSA.
  2. It looks up the agent's public keys with the kid. Revoked keys are skipped.
  3. It verifies the Ed25519 signature with the public key. The database holds only public keys, so a database leak cannot be used to forge tokens.
  4. It checks exp and iat with 30 seconds of skew, rejects tokens with a purpose or sub: "server", and checks aud when present.
  5. It reads sub, tid, locale, role and claims, and ties the session to that user and tenant.

Revocation

There is no per-token revocation list. Tokens are short-lived instead, and revoking a secret key in the console stops it at once: tokens signed by a revoked key fail on their next request.

To cut off one user, stop issuing tokens for them and wait at most one token lifetime. Use a short ttlSeconds if that window matters to you.

A session belongs to the tenant of the token that started it. A token with a different tenant, or none, cannot continue it, and the runtime answers session_not_found.

Next steps

On this page