@hiyve/react-identity

React components and hooks for Hiyve Identity authentication — login, registration, two-factor authentication, password management, email verification, OAuth 2.1/PKCE clients, MCP tokens, and trusted device management.

Installation

npm install @hiyve/react-identity @hiyve/identity-client
Copy

Peer Dependencies

npm install react @mui/material @mui/icons-material @emotion/react @emotion/styled @hiyve/utilities
Copy

Quick Start

Zero-Config with Server Proxy (Recommended)

When your Express server uses @hiyve/admin middleware (mountHiyveRoutes), the API key stays server-side and IdentityProvider needs no props:

import { IdentityProvider, AuthFlow } from '@hiyve/react-identity';

function App() {
  return (
    <IdentityProvider>
      <AuthFlow
        onAuthenticated={(user) => console.log('Logged in:', user)}
        onRegistered={(user) => console.log('Registered:', user)}
      />
    </IdentityProvider>
  );
}
Copy

Requests are proxied through your server at /api/hiyve/identity/*, which injects the API key and forwards to Hiyve Cloud.

Direct Mode (API Key in Client)

If you prefer to connect directly to Hiyve Cloud without a server proxy:

<IdentityProvider apiKey="pk_live_xxx">
  <AuthFlow onAuthenticated={handleAuth} />
</IdentityProvider>
Copy

Handle Password Reset and Email Verification

Pass tokens from your URL to AuthFlow to show the correct view automatically:

const params = new URLSearchParams(location.search);

<AuthFlow
  resetToken={params.get('reset_token') || undefined}
  verificationToken={params.get('verify_token') || undefined}
  onAuthenticated={handleAuth}
/>
Copy

Note: Email verification and TFA are independently configurable per-organization on the server. When email verification is disabled, users are created with emailVerified: true and no verification email is sent. When TFA is disabled, login always returns tokens directly. See the Server Integration Guide for configuration details.

Individual Forms

Use forms directly with your own routing:

import { IdentityProvider, LoginForm } from '@hiyve/react-identity';

function LoginPage() {
  return (
    <LoginForm
      onSuccess={() => navigate('/dashboard')}
      onTfaRequired={() => navigate('/verify')}
      onForgotPassword={() => navigate('/forgot-password')}
      onRegister={() => navigate('/register')}
    />
  );
}
Copy

Provider

IdentityProvider

Wrap your application (or the authenticated portion) with IdentityProvider to enable all hooks and components.

<IdentityProvider
  apiKey="pk_test_xxx"
  environment="development"
  tokenStorage="memory"
>
  <App />
</IdentityProvider>
Copy

Hooks

function Profile() {
  const { user, isAuthenticated } = useUser();
  const { logout } = useAuthActions();

  if (!isAuthenticated) return <p>Not logged in</p>;
  return <button onClick={logout}>Logout {user?.email}</button>;
}
Copy

function Header() {
  const identity = useIdentitySafe();
  return (
    <header>
      {identity?.isAuthenticated
        ? <span>{identity.user?.email}</span>
        : <a href="/login">Sign In</a>}
    </header>
  );
}
Copy

function Dashboard() {
  const authFetch = useAuthFetch();
  const [data, setData] = useState(null);

  useEffect(() => {
    authFetch('/api/dashboard')
      .then((r) => r.json())
      .then(setData);
  }, [authFetch]);

  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}
Copy

function ProfilePage() {
  const { profile, isLoading, error, updateProfile } = useProfile();

  if (isLoading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <p>Hello, {profile?.name}</p>
      <button onClick={() => updateProfile({ name: 'New Name' })}>
        Update Name
      </button>
    </div>
  );
}
Copy

Roles

AuthUser.roles is an additive array of role names sourced from the identity profile's roles field. Roles are feature-scoped memberships used for gating — distinct from the single persona string (e.g. metadata.role === 'teacher') which drives routing.

import { useHasRole, ROLE_PUBLIC_FILES } from '@hiyve/react-identity';

function Library() {
  const canSeePublic = useHasRole(ROLE_PUBLIC_FILES);
  return canSeePublic ? <PublicScopeTab /> : null;
}
Copy

Exported role-name constants (use these instead of string literals to prevent typo drift):

See the FileManager Public Files section for how these gate the scope selector.

Auth Form Components

Management Panel Components

AuthFlow

State machine that composes all auth forms with automatic transitions between login, register, forgot password, TFA, reset password, and email verification.

Customization

All components accept labels, colors, styles, and icons props. Override individual values — unspecified values use defaults.

<LoginForm
  labels={{ title: 'Welcome Back', submitButton: 'Log In' }}
  colors={{ submitButton: '#6200ea', linkText: '#6200ea' }}
  styles={{ borderRadius: 12, maxWidth: 360 }}
  icons={{ email: <MyEmailIcon /> }}
/>
Copy

Use the exported default* objects to see all available keys:

import { defaultLoginFormLabels, buildDefaultLoginFormColors } from '@hiyve/react-identity';
// `buildDefaultLoginFormColors(theme)` is a theme-aware factory; pass the MUI Theme:
// const colors = buildDefaultLoginFormColors(useTheme());
Copy

Use merge* functions for programmatic overrides:

import { mergeLoginFormLabels } from '@hiyve/react-identity';

const labels = mergeLoginFormLabels({ title: 'Welcome' });
Copy

Available Defaults & Merge Functions

Note: All buildDefault*Colors exports are theme-aware factories that take the current MUI Theme and return a colors object. Call buildDefaultLoginFormColors(useTheme()) (etc.) to get a defaulted colors object compatible with the corresponding merge*Colors function.

Error Handling

All components accept an onError callback and also display errors inline with dismissible alerts:

<LoginForm onError={(err) => analytics.track('login_error', { message: err.message })} />
Copy

MUI sx Prop

All components accept the MUI sx prop for additional styling:

<LoginForm sx={{ p: 4, border: '1px solid #e0e0e0' }} />
Copy

Key Types

All component customization types and core auth types are exported from @hiyve/react-identity:

Provider & auth state

AuthFlow orchestrator

Per-component customization types

Each component exports *Props, *Labels, *Colors, *Styles, and *Icons types:

• LoginForm* — LoginFormProps, LoginFormLabels, LoginFormColors, LoginFormStyles, LoginFormIcons
• RegisterForm* — RegisterFormProps, RegisterFormLabels, RegisterFormColors, RegisterFormStyles, RegisterFormIcons
• TfaVerification* — TfaVerificationProps, TfaVerificationLabels, TfaVerificationColors, TfaVerificationStyles, TfaVerificationIcons
• PasswordResetRequest* — PasswordResetRequestProps, PasswordResetRequestLabels, PasswordResetRequestColors, PasswordResetRequestStyles, PasswordResetRequestIcons
• PasswordResetForm* — PasswordResetFormProps, PasswordResetFormLabels, PasswordResetFormColors, PasswordResetFormStyles, PasswordResetFormIcons
• EmailVerification* — EmailVerificationProps, EmailVerificationLabels, EmailVerificationColors, EmailVerificationStyles, EmailVerificationIcons
• UserProfile* — UserProfileProps, UserProfileLabels, UserProfileColors, UserProfileStyles, UserProfileIcons
• DeviceManagement* — DeviceManagementProps, DeviceManagementLabels, DeviceManagementColors, DeviceManagementStyles, DeviceManagementIcons
• McpTokenManagement* — McpTokenManagementProps, McpTokenManagementLabels, McpTokenManagementColors, McpTokenManagementStyles, McpTokenManagementIcons
• OAuthClientManagement* — OAuthClientManagementProps, OAuthClientManagementLabels, OAuthClientManagementColors, OAuthClientManagementStyles, OAuthClientManagementIcons

Identity Bridge (CloudProvider Integration)

When IdentityProvider is mounted above CloudProvider (from @hiyve/react-intelligence) or HiyveProvider (from @hiyve/react), the authenticated user's email is automatically available to those providers. This allows cloud tokens to be generated for the correct user without passing userId manually.

import { IdentityProvider } from '@hiyve/react-identity';
import { CloudProvider } from '@hiyve/react-intelligence';
import { HiyveProvider } from '@hiyve/react';

// Zero-config: IdentityProvider shares the user email,
// CloudProvider and HiyveProvider auto-generate cloud tokens.
function App() {
  return (
    <IdentityProvider>
      <CloudProvider>
        <HiyveProvider generateRoomToken={generateRoomToken}>
          <MyApp />
        </HiyveProvider>
      </CloudProvider>
    </IdentityProvider>
  );
}
Copy

Requirements

• IdentityProvider must wrap all identity components and hooks
• @hiyve/identity-client must be installed as a peer dependency
• @hiyve/react must be installed as a peer dependency (for identity bridge context)
• MUI v5 or v6 with Emotion for component rendering
• @hiyve/utilities for avatar helpers in UserProfile