Authentication and identity

Partition browser state with server-derived identity and session epochs.

Connect the frontend client’s identity to your application’s authenticated session.

From this guide’s application/package root, install only its selected requirements:

bun add @opentelemetry/api@1.9.1 @relkit/better-auth@0.8.2 @relkit/client@0.8.2 'react@>=18.0.0'

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in dependencies; build/type tooling belongs in devDependencies. Installing an adapter does not supply its optional SDK peers or enable the feature’s configuration.

This convenience leaf keeps backend database configuration out of the browser. The example below also uses Better Auth’s native React createAuthClient and useSession hook, so install its browser SDK requirements:

Before installing, merge these selected declaration repairs into the existing package manifest, preserving unrelated overrides:

{
  "overrides": {
    "@better-fetch/fetch": "1.3.2"
  },
  "pnpm": {
    "overrides": {
      "@better-fetch/fetch": "1.3.2"
    }
  }
}

From this guide’s application/package root, install only its selected requirements:

bun add better-auth@1.7.1
bun add --dev @cloudflare/workers-types@4.20250121.0

The auth module owns sign-up, sign-in, and session operations.

Bootstrap identity

GET /_relkit/v1/client/identity is private and non-cacheable. It returns opaque identity scope, session epoch, application ID, and public fingerprint. Scope or epoch changes abort in-flight work, clear private RELKIT stores, grants, and presence, and reject late callbacks.

Connect a provider

Use BetterAuthRelkitClientProvider from @relkit/better-auth/react for cookie sessions. A manual identityKey adds a tenant/application partition but never grants authority. Cross-origin cookies still require exact credentialed CORS, suitable cookie SameSite policy, CSRF protection, and an allowed Origin.

"use client";

/** Connects the native browser session hook to RELKIT's identity-scoped client cache. */
import { BetterAuthRelkitClientProvider } from "@relkit/better-auth/react";
import { createAuthClient } from "better-auth/react";
import type { ReactNode } from "react";

export const authClient = createAuthClient({ basePath: "/api/auth" });

/** Remounts private client state when the browser's authenticated session changes.
 * @param props - Frontend content that consumes RELKIT hooks.
 * @returns A same-origin provider whose auth endpoints use the native Better Auth client. */
export function AuthProvider({ children }: { readonly children: ReactNode }) {
  return (
    <BetterAuthRelkitClientProvider authClient={authClient}>
      {children}
    </BetterAuthRelkitClientProvider>
  );
}

Wrap the part of your app that calls RELKIT hooks in AuthProvider. For a same-origin proxy, forward the backend’s /api/auth mount as well as /rpc and /_relkit, and configure Better Auth’s trusted origins for the frontend. Do not nest a second generic provider around private queries. The wrapper responds to native session changes; it does not replace the server’s authorization.

Reference: BetterAuthRelkitClientProvider.

Reference and source