@identia/react

React hooks, provider, and guard components for the Identia CIAM platform. Built on @identia/sdk, this package gives you feature flags, permissions, entitlements, and impersonation as React primitives.

Installation

npm install @identia/react @identia/sdk

Quick Start

import { IdentiaProvider, useFeatureFlag, RequirePermission } from '@identia/react';

function App() {
  return (
    <IdentiaProvider
      domain="your-tenant.accessiq.app"
      apiKey="your-sdk-api-key"
      getAccessToken={() => localStorage.getItem('accessToken')}
    >
      <Dashboard />
    </IdentiaProvider>
  );
}

function Dashboard() {
  const showBeta = useFeatureFlag('beta-dashboard');

  return (
    <div>
      {showBeta && <BetaBanner />}
      <RequirePermission permission="reports:view" fallback={<AccessDenied />}>
        <Reports />
      </RequirePermission>
    </div>
  );
}

Features

| Feature | Description | |---------|-------------| | IdentiaProvider | Initializes the SDK and provides context to all hooks and guards | | Feature Flags | useFeatureFlag, useFeatureFlags hooks for real-time flag evaluation | | Permissions | useHasPermission, useHasRole, usePermissions hooks | | Entitlements | useEntitlements, useQuota hooks for plan-based enforcement | | Guard Components | FeatureFlag, RequirePermission, RequireRole, RequireEntitlement | | Organizations | useOrganizations hook for multi-org context switching | | Impersonation | HandoffBootstrap, ImpersonationBanner for support flows | | Events | useIdentiaEvent hook for SDK event subscriptions |

Provider

import { IdentiaProvider } from '@identia/react';

<IdentiaProvider
  domain="tenant.accessiq.app"
  apiKey="sdk-api-key"
  getAccessToken={() => authClient.getAccessToken()}
  onError={(err) => console.error(err)}
>
  {children}
</IdentiaProvider>

Hooks

useFeatureFlag / useFeatureFlags

import { useFeatureFlag, useFeatureFlags } from '@identia/react';

const isEnabled = useFeatureFlag('new-checkout');        // boolean

const { flags, isLoading } = useFeatureFlags();
// flags: Record<string, { enabled, variant, metadata }>

useHasPermission / useHasRole

import { useHasPermission, useHasRole } from '@identia/react';

const canEdit = useHasPermission('orders:edit');         // boolean
const isAdmin = useHasRole('admin');                     // boolean

usePermissions

import { usePermissions } from '@identia/react';

const { permissions, hasPermission, hasRole, isLoading } = usePermissions();

useEntitlements / useQuota

import { useEntitlements, useQuota } from '@identia/react';

const { hasEntitlement, entitlements } = useEntitlements();
const showAnalytics = hasEntitlement('advanced-analytics');

const { limit, used, remaining } = useQuota('api-calls');

useOrganizations

import { useOrganizations } from '@identia/react';

const { organizations, currentOrg, switchOrg } = useOrganizations();

useIdentiaEvent

import { useIdentiaEvent } from '@identia/react';

useIdentiaEvent('flags_updated', (flags) => {
  console.log('Flags changed:', flags);
});

Guard Components

Declarative access control — renders children only when the condition is met.

FeatureFlag

import { FeatureFlag } from '@identia/react';

<FeatureFlag name="beta-feature" fallback={<ComingSoon />}>
  <BetaFeature />
</FeatureFlag>

RequirePermission

import { RequirePermission } from '@identia/react';

<RequirePermission permission="users:manage" fallback={<AccessDenied />}>
  <UserManagement />
</RequirePermission>

RequireRole

import { RequireRole } from '@identia/react';

<RequireRole role="admin" fallback={<AccessDenied />}>
  <AdminPanel />
</RequireRole>

RequireEntitlement

import { RequireEntitlement } from '@identia/react';

<RequireEntitlement entitlement="advanced-reporting" fallback={<UpgradePrompt />}>
  <AdvancedReports />
</RequireEntitlement>

Impersonation

For support agents impersonating end users:

import { HandoffBootstrap, ImpersonationBanner } from '@identia/react/impersonation';

// In your app layout — shows a banner when impersonating
<ImpersonationBanner />

// On your callback route — exchanges handoff code for session
<HandoffBootstrap
  domain="tenant.accessiq.app"
  onReady={(session) => setUser(session.targetUser)}
/>

Next.js Support

Server-side handoff handler for Next.js API routes:

import { createHandoffHandler } from '@identia/react/nextjs';

export const POST = createHandoffHandler({
  domain: 'tenant.accessiq.app',
});

Related Packages

| Package | Description | |---------|-------------| | @identia/sdk | TypeScript SDK (used internally) | | @identia/auth-core | Framework-agnostic auth engine (OIDC, PKCE, passkeys) | | @identia/auth-react | React auth components (LoginPage, AuthGuard, useAuth) | | Identia.AspNetCore | .NET SDK for ASP.NET Core backends |

License

MIT