Skip to Content
Baseera Docs

Signing user tokens

Every claim and option of signUserToken, the limits, and why only EdDSA is accepted.

A user token tells Baseera which user is in a session and which of your customers (tenant) they belong to. Your server signs it with the agent's secret key, after it has checked who is signed in. The browser sends it with every request.

import { signUserToken } from "@baseera/node";

const token = await signUserToken(
  { userId: user.id, tenantId: org.id, name: user.name, locale: "ar", role: "accountant" },
  process.env.BASEERA_SECRET_KEY!,
);

Call it on your server only. A secret key must never reach the browser.

Signature

function signUserToken(input: UserTokenInput, secretKey: string, options?: SignUserTokenOptions): Promise<string>;

Input

Prop

Type

Options

Prop

Type

The constants USER_TOKEN_DEFAULT_TTL_SECONDS (900) and USER_TOKEN_MAX_TTL_SECONDS (3600) are exported.

The token

It is a JWT. The header is { "alg": "EdDSA", "typ": "JWT", "kid": "..." }, where kid is the first 16 hex characters of the agent's public key, so the runtime finds the right key after a rotation.

ClaimFrom
subuserId
tidtenantId
namename
localelocale
rolerole
claimsclaims, always lists of strings after signing
audoptions.agentId
iatThe issue time, in seconds.
expiat plus ttlSeconds.

Nothing else is stored. The runtime allows 30 seconds of clock skew when it checks iat and exp.

Only EdDSA

A secret key is sk_ plus a random 32-byte Ed25519 seed, generated by the platform and shown once. Baseera stores only the matching public key, so a database leak cannot be used to forge a token. The runtime accepts alg: EdDSA and nothing else: none and the HS, RS and ES families are refused before any key is read, which also closes the classic attack of signing with HMAC using the public key as the secret.

You do not choose an algorithm. signUserToken always signs with EdDSA.

Custom claims

Add role and claims to keep some documents from some users. Give the documents access rules when you push them, and a user whose token lacks a claim never gets a restricted document from a search, a citation or a source link.

const token = await signUserToken(
  {
    userId: user.id,
    tenantId: org.id,
    role: "staff",
    claims: { plan: "pro", groups: ["finance", "admin"] },
  },
  process.env.BASEERA_SECRET_KEY!,
);

Claims are signed with the rest of the token, so users cannot choose their own. Limits:

  • At most 10 names. A name matches ^[A-Za-z0-9_.-]{1,64}$.
  • Each name has 1 to 20 values. Each value is a string of 1 to 100 characters with no control characters.
  • 2,048 bytes in all, serialized.

Nothing is repaired. A set that breaks a limit throws TypeError when you sign, and a token that arrives with invalid claims is refused by the runtime, because silently dropping a claim could widen or narrow access unnoticed.

Lifetime and refresh

The default lifetime is 15 minutes and the maximum is 1 hour. You do not refresh tokens yourself. BaseeraProvider calls your getUserToken function lazily, and again when the cached token has less than a minute left or the runtime says it expired. Return a fresh token from your route each time.

What it throws

signUserToken throws before it signs when something is wrong. Catch it in your route and answer with a generic 500, never the message to the user.

ConditionError
The key is not sk_ and 64 hex characters, or it is a publishable keyTypeError
userId missing, or a field is not a stringTypeError
A field is longer than its limitRangeError
locale is not a BCP 47 tagTypeError
claims break a limitTypeError
ttlSeconds is not a whole number from 1 to 3600RangeError

Do not

  • Do not sign tokens in the browser, or send a secret key to it.
  • Do not accept a userId from the request body. Take it from your own session.
  • Do not cache a token across users. Set cache-control: no-store on the route.

Next steps

On this page