React SDK

@wocha/react provides React hooks and headless components for Wocha authentication in single-page applications. It implements OAuth 2.0 authorisation code with PKCE as a public client.

Installation

pnpm add @wocha/react

Or scaffold with the CLI

npx @wocha/cli init --framework react-spa

Quick start

import { WochaProvider } from "@wocha/react";
 
const config = {
  issuer: "https://my-tenant.auth.wocha.ai",
  clientId: "your-client-id",
  redirectUri: window.location.origin + "/callback",
};
 
export function App({ children }: { children: React.ReactNode }) {
  return <WochaProvider config={config}>{children}</WochaProvider>;
}

Hooks

All hooks must be used inside WochaProvider.

`useSession()`

const { data, status, error, refresh, login, logout } = useSession();
// data: GreetUser | null
// status: "loading" | "authenticated" | "unauthenticated"

`useOrg()`

Switch organisation context when the user belongs to multiple orgs:

const { orgId, orgIds, switchOrg } = useOrg();
await switchOrg("org_xyz");

`useProductOrgs(productSlug)`

Filter organisations to only those linked to a specific product:

const { orgs, orgIds, isLoading } = useProductOrgs("chancery");
// orgs: ProductOrg[] with id, slug, display_name, role, joined_at
// orgIds: string[] of slugs for the filtered orgs

Calls GET /api/v1/account/organisations?product=<slug> and returns only organisations where the product has been provisioned. Falls back to the full org_ids list if the call fails or the product has no linked organisations.

`usePermissions()`

Check SpiceDB permissions client-side when apiUrl is configured:

const { check, checks } = usePermissions();
const allowed = await check("document:123", "viewer");

Components

Headless components are available for common UI patterns:

import { SignIn, SignOut, Protect } from "@wocha/react";
 
<Protect permission="admin">
  <AdminPanel />
</Protect>

For pre-built UI, see @wocha/ui.

Learn more

React quickstart
Next.js SDK — for App Router with server-side sessions

React SDK

On this page