@acl-identity/react

React integration for the ACL Identity SDK. Provides AuthProvider, the useAuth hook, and ready-made components for sign-in, sign-out, and OAuth2 callback handling.

Installation

npm install @acl-identity/react
# or
pnpm add @acl-identity/react

Requires React 18 or later as a peer dependency.

Quick start

1. Create the client and wrap your app

import { ACLBrowserClient, AuthProvider } from '@acl-identity/react';

const client = new ACLBrowserClient({
  baseUrl: 'https://auth.example.com',
  clientId: 'my-client-id',
  redirectUri: 'https://app.example.com/callback',
  orgSlug: 'my-org',
});

function App() {
  return (
    <AuthProvider
      client={client}
      clientId="my-client-id"
      redirectUri="https://app.example.com/callback"
      orgSlug="my-org"
      onRedirectCallback={(appState) => {
        // navigate to appState?.returnTo after login
      }}
    >
      <YourApp />
    </AuthProvider>
  );
}

2. Use the useAuth hook

import { useAuth } from '@acl-identity/react';

function Header() {
  const { user, isAuthenticated, isLoading, signIn, signOut } = useAuth();

  if (isLoading) return <Spinner />;

  if (!isAuthenticated) {
    return <button onClick={() => signIn()}>Sign in</button>;
  }

  return (
    <div>
      <span>Welcome, {user?.name}</span>
      <button onClick={() => signOut()}>Sign out</button>
    </div>
  );
}

3. Handle the OAuth2 callback

Add a callback page that renders <CallbackHandler />:

import { CallbackHandler } from '@acl-identity/react';
import { useNavigate } from 'react-router-dom';

export function CallbackPage() {
  const navigate = useNavigate();
  return (
    <CallbackHandler
      onSuccess={() => navigate('/')}
      onError={(err) => console.error(err)}
    />
  );
}

Components

| Component | Description | |---|---| | AuthProvider | Context provider — wraps your app | | CallbackHandler | Processes the OAuth2 redirect callback | | SignInButton | Pre-wired sign-in button | | SignOutButton | Pre-wired sign-out button | | SilentCallbackPage | Placed at silentRedirectUri for iframe-based silent renewal |

Silent token renewal

Mount <SilentCallbackPage /> at a dedicated route (e.g. /silent-callback) and pass its URL to AuthProvider:

<AuthProvider
  ...
  silentRedirectUri="https://app.example.com/silent-callback"
>

Tokens are renewed automatically before they expire without a visible redirect.

useAuth return value

| Field | Type | Description | |---|---|---| | user | UserClaims \| null | Decoded JWT claims of the current user | | isAuthenticated | boolean | Whether a valid token exists | | isLoading | boolean | True while the initial session check is in progress | | error | Error \| null | Last auth error | | signIn(options?) | Promise<void> | Redirects to the authorization server | | signOut(options?) | Promise<void> | Clears tokens and optionally revokes them | | getAccessToken() | Promise<string \| null> | Returns the current access token | | handleCallback(url?) | Promise<{ appState? }> | Manually processes a callback URL |

License

MIT