Authentication

Establish an end-user session

Authentication covers end-user account/session flows and their separation from platform and developer credentials.

Mixing credential classes can expose administrative authority to browsers or break RLS scope.

Use it when implementing registration, sign-in, refresh, password reset, verification, sessions, or sign-out.

Requirements for Authentication

• Prerequisite — A project with auth settings and email delivery configured.
• Prerequisite — A runtime-appropriate SessionStore and an exact public origin.
• Required value — User email/password or one-time token, project ID, client base URL, and session-storage key.
• Required value — For administration only: platform login or scoped developer key kept outside client bundles.

End-user sessions

The client stores the returned access/refresh pair, deduplicates concurrent refreshes, and retries one unauthorized end-user request after a successful rotation.

await ffdb.auth.register({ email, password });
await ffdb.auth.verifyEmail(token);

const session = await ffdb.auth.signIn(email, password);
const sessions = await ffdb.auth.sessions();
await ffdb.auth.signOut();

Developer credentials

Platform sessions manage organizations and projects. Project developer keys manage schema, policies, buckets, backups, and administrative SQL. End-user access tokens carry project-scoped subject and claims for RLS.

Install the versioned email components

@ffdb/email-components contains the release's React Email defaults and allowed-variable manifest. Install its exact server-matched npm version, or use the checksum-listed tarball from the matching GitHub tag for offline workflows. An application does not need it merely to register or sign in users.

VERSION=0.3.0
npm install --save-exact "@ffdb/email-components@$VERSION"

Authentication workflow

• 1. Configure project auth and email templates.
• 2. Construct the client with a session store.
• 3. Register or sign in and observe the returned user/session.
• 4. Let the client rotate short-lived access tokens.
• 5. Sign out and verify local plus server session invalidation.

Verify authentication

The client exposes the correct authenticated user and subsequent queries run under that immutable verified scope.

Troubleshoot authentication

• Refresh is rejected — clear the invalid session and require sign-in.
• Email never arrives — inspect the outbox/provider status with the request ID, without exposing tokens.

Continue from Authentication

• Define JWT-claim policies.
• Test session revocation and multi-user RLS.