@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 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

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, defaultLoginFormColors } from '@hiyve/react-identity';
Copy

Use merge* functions for programmatic overrides:

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

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

Available Defaults & Merge Functions

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

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