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.
| Claim | From |
|---|---|
sub | userId |
tid | tenantId |
name | name |
locale | locale |
role | role |
claims | claims, always lists of strings after signing |
aud | options.agentId |
iat | The issue time, in seconds. |
exp | iat 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.
| Condition | Error |
|---|---|
The key is not sk_ and 64 hex characters, or it is a publishable key | TypeError |
userId missing, or a field is not a string | TypeError |
| A field is longer than its limit | RangeError |
locale is not a BCP 47 tag | TypeError |
claims break a limit | TypeError |
ttlSeconds is not a whole number from 1 to 3600 | RangeError |
Do not
- Do not sign tokens in the browser, or send a secret key to it.
- Do not accept a
userIdfrom the request body. Take it from your own session. - Do not cache a token across users. Set
cache-control: no-storeon the route.