Identity.Base Docs

React SDK

`@identity-base/react-client` is the official React SDK for Identity Base. It wraps the authorization-code PKCE flow, manages access and refresh tokens, and exposes hooks for registration, login, MFA, profile updates, permissions, and admin-facing operations.

bash

npm install @identity-base/react-client

tsx

import {
  IdentityProvider,
  useAuth,
  useIdentityContext,
} from '@identity-base/react-client';

// Wrap your app with the provider
<IdentityProvider
  config={{
    apiBase: "https://identity.example.com",
    clientId: "spa-client",
    redirectUri: "https://app.example.com/auth/callback",
    scope: "openid profile email identity.api",
    tokenStorage: "localStorage",
    autoRefresh: true
  }}
>
  <App />
</IdentityProvider>

// Use the hook in components
const {
  user,
  isAuthenticated,
  isLoading,
  error,
  refreshUser,
  logout,
} = useAuth();

// Use the context for imperative and typed admin operations
const { authManager } = useIdentityContext();
const principals = await authManager.admin.servicePrincipals.list({ page: 1 });

Key hooks and workflows

`useAuth()` returns user, authentication/loading/error state, `refreshUser`, and `logout`.
`useIdentityContext()` exposes the imperative auth manager and its typed admin namespaces.
`useLogin()` / `useRegister()` cover sign-in and registration with profile metadata.
`useMfa()` handles authenticator, email, SMS, and recovery-code flows.
`useProfile()` manages `/users/me` and concurrency-aware profile updates.
`usePermissions()` and admin hooks let the SPA adapt based on effective permission claims.
Provider initialization keeps loading state active during meaningful config changes and exposes non-401 initialization failures through `error`.

Organizations add-on

tsx

npm install @identity-base/react-organizations

import {
  OrganizationsProvider,
  useOrganizationSwitcher,
} from '@identity-base/react-organizations';

<IdentityProvider config={identityConfig}>
  <OrganizationsProvider apiBase={identityConfig.apiBase}>
    <App />
  </OrganizationsProvider>
</IdentityProvider>

const { switchOrganization, isSwitching, error } =
  useOrganizationSwitcher();

await switchOrganization(organizationId);

OrganizationsProvider loads all membership pages, persists the active organization locally, and clears state on logout.
Membership and organization request failures remain separate from valid empty results, and stale in-flight responses are ignored.
useOrganizations() exposes membership, organization, loading, error, active-context, reload, and typed client state.
Switching organization changes client-side context and does not refresh claims automatically; call authManager.refreshTokens() when updated org:* claims are required.