Tokens, sessions and the SDK

import { createClient } from '@chelabase/client';

const db = createClient({ url: 'http://api.chelabase.localhost:8000', key: 'chk_pub_…' });
await db.auth.signUp({ email: 'ann@example.com', password: 'Str0ng!pass', data: { display_name: 'Ann' } });
const mine = await db.from('users').select('id', 'display_name'); // only the signed-in user's row

signUp creates the user and, with email verification off, signs them in. After that the client sends the user's token with every data API request, which runs as authenticated with the user's claims. The public key alone (no signed-in user) runs as anon.

The SDKCopy Anchor Link

db.auth has these methods. Types come from @chelabase/client.

The client keeps the refresh token in localStorage in browsers and in memory elsewhere. Pass your own { get, set, remove } (sync or async) as auth.storage to change that, and auth.autoRefresh: false to turn off the background refresh timer:

import { createClient } from '@chelabase/client';

const values = new Map<string, string>();

const db = createClient({
  url: 'http://api.chelabase.localhost:8000',
  key: 'chk_pub_…',
  auth: {
    storage: {
      get: (key) => values.get(key) ?? null,
      set: (key, value) => void values.set(key, value),
      remove: (key) => void values.delete(key),
    },
  },
});

const stop = db.auth.onChange((event, user) => {
  console.log(event, user?.email);
});
stop();

FlowsCopy Anchor Link

The flows live under /auth/v1/app/ on the gateway and take a public key as Authorization: Bearer <key> (a secret key is refused), except jwks, which needs no key:

jwks is public: your own servers can verify access tokens with it. The credential flows are rate limited, and sign-up and sign-in answer after a minimum response time, so they don't give away whether an account exists. With email verification on, sign-up and resend-code answer the same for a taken address; with verification off, sign-up for a taken email is 409 email_taken.

Passwords need at least 8 characters, with a lowercase letter, an uppercase letter, a digit and a symbol, and at most 72 bytes (422 weak_password otherwise).

Access tokenCopy Anchor Link

An EdDSA-signed JWT with these claims:

It is valid for CHELABASE_APP_ACCESS_TTL_SECS (default 900, so 15 minutes). Requests send it as Chelabase-User: <token> beside Authorization: Bearer <public key>; the client does this for you.

The gateway checks the token and that its session is still live. Liveness is cached for 30 seconds, so a revocation reaches the data API within 30 seconds. The gateway never falls back to anon:

Refresh tokenCopy Anchor Link

A string of the form <session id>.<secret>. It expires on a sliding schedule of CHELABASE_APP_REFRESH_TTL_SECS (default 30 days), capped at 90 days from sign-in.

• Every refresh rotates it.
• Within 10 seconds of a rotation, presenting the previous token returns the same new pair (two tabs refreshing at once).
• After that, presenting it revokes the session: 401 refresh_token_reused.

The client refreshes 60 seconds before the access token expires, refreshes first when a request would carry a token with under 5 seconds left, and refreshes once after a data request answers 401 user_token_expired. It signs out locally (and emits signed_out) when a refresh answers refresh_token_reused, refresh_token_invalid, user_session_revoked or user_inactive, or when any request answers user_session_revoked.

Password changesCopy Anchor Link

A password change (change-password) ends the user's other sessions; the caller gets a fresh pair. A password reset ends all of them.

ErrorsCopy Anchor Link

The codes above, plus the sign-up and sign-in answers:

All codes are listed in Error codes.