---
title: Authentication and identity
description: Partition browser state with server-derived identity and session epochs.
pagination: false
sidebar:
  icon: shield-check
---

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

> **Before you begin**
>
> Complete [React client setup](/docs/modules/client) in the frontend and [Better Auth
> setup](/docs/modules/auth/better-auth) in the backend first. The React convenience provider uses
> the separate `@relkit/better-auth/react` leaf. Add only its selected frontend owner/peers:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

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

```sh
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:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

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

```json
{
  "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:

```sh
bun add better-auth@1.7.1
bun add --dev @cloudflare/workers-types@4.20250121.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.

The [auth module](/docs/modules/auth/clients) 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.

```tsx title="src/AuthProvider.tsx"
"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`](/docs/api/better-auth#betterauthrelkitclientprovider).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/auth-provider.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/auth-provider.tsx)