@atzentis/auth-react

React hooks and components for auth.atzentis.com. Built on top of @atzentis/auth-sdk with full TanStack Query integration, 40+ pre-built components, and localization support.

Features

• AuthProvider — wraps QueryClientProvider internally, supports SSR hydration via initialUser, and fires callbacks for session expiry, token refresh, and new device alerts
• 14 mutation hooks — one hook per auth operation, all backed by TanStack Query mutations
• 12 query hooks — reactive queries for user, session, devices, sessions, organizations, API keys, login activity, and more
• 40+ components — complete auth flows, settings cards, organization management, and RBAC guards
• Centralized localization — ~341 keys, fully replaceable per component via the localization prop
• SSR support — separate server entry point (@atzentis/auth-react/server) with no "use client" banner

Installation

npm install @atzentis/auth-react @atzentis/auth-sdk @tanstack/react-query
# or
pnpm add @atzentis/auth-react @atzentis/auth-sdk @tanstack/react-query

Quick Start

Wrap your application with AuthProvider:

import { AuthProvider } from "@atzentis/auth-react";

function App() {
  return (
    <AuthProvider
      baseUrl="https://auth.atzentis.com"
      onSessionExpired={() => router.push("/login")}
      onTokenRefreshed={(session) => console.log("Refreshed", session.id)}
      onNewDeviceAlert={(alert) => console.warn("New device", alert)}
    >
      <YourApp />
    </AuthProvider>
  );
}

Use hooks in your components:

import { useAuth, useSession, useUser } from "@atzentis/auth-react";

function Dashboard() {
  const { signInWithEmail, signOut, isAuthenticated } = useAuth();
  const { data: session, isLoading } = useSession();
  const { data: user } = useUser();

  if (isLoading) return <Spinner />;

  if (!isAuthenticated) {
    return (
      <button onClick={() => signInWithEmail({ email, password })}>
        Sign in
      </button>
    );
  }

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

Hooks

Auth and Session

| Hook | Purpose | | --- | --- | | useAuth() | Facade over all auth mutations. Provides signInWithEmail, signInWithUsername, signInWithOAuth, signInWithPhone, signInWithMagicLink, signUp, signOut, requestPasswordReset, resetPassword, sendVerificationEmail, verifyEmail, and more (22 methods total) | | useSession() | Read-only access to the current session | | useSessions() | List and manage all sessions; deviceSessions and refresh() | | useAuthenticate() | Programmatic navigation helper for auth redirects |

User and Profile

| Hook | Purpose | | --- | --- | | useUser() | Fetch and update the current user profile (12 methods) | | usePhone() | Send OTP, verify phone number, phone sign-in | | usePasskeys() | Register, authenticate, list, rename, and remove passkeys |

Devices and Activity

| Hook | Purpose | | --- | --- | | useDevices() | List devices, trust/untrust, remove; refresh() required to load | | useLoginActivity() | Paginated login event history with filtering; refresh() required |

Organizations and API Keys

| Hook | Purpose | | --- | --- | | useOrganizations() | 14 methods — full organization CRUD, member and invitation management | | useApiKeys() | 8 methods — create, rotate, revoke, validate, and track usage |

Utility

| Hook | Purpose | | --- | --- | | useAuthClient() | Direct access to the underlying AuthClient instance | | useAuthLocalization() | Access the active localization strings |

Components

Auth Forms

| Component | Description | | --- | --- | | LoginForm | Email/password login with optional OAuth buttons | | SignupForm | New account creation | | PhoneLoginForm | Two-step phone + OTP login | | MagicLinkForm | Passwordless magic link request | | OAuthButton | Single OAuth provider button (google, apple, github) |

Auth Flows

| Component | Description | | --- | --- | | ForgotPasswordForm | Email input to request a password reset | | ResetPasswordForm | Token-based new password form | | EmailVerificationForm | Verify email with a code or link | | EmailOTPForm | OTP code entry for email-based auth | | TwoFactorForm | TOTP code entry with backup code fallback | | RecoverAccountForm | 4-step account recovery wizard | | AuthView | Route-based renderer — maps pathname strings to the correct form |

Settings Cards

| Component | Description | | --- | --- | | ChangePasswordCard | Update account password | | ChangeEmailCard | Update email address | | UpdateNameCard | Update display name | | UpdateUsernameCard | Update username with debounced availability check | | UpdateAvatarCard | Upload and preview a profile avatar | | SessionsCard | View and revoke active sessions | | ProvidersCard | Connect and disconnect OAuth providers | | TwoFactorCard | Enable/disable two-factor authentication | | PasskeysCard | Manage WebAuthn passkeys | | ApiKeysCard | Create, view, rotate, and revoke API keys | | DeleteAccountCard | Three-step account deletion confirmation | | AccountView | Orchestrator — renders all settings sections in one view |

Organization Components

| Component | Description | | --- | --- | | CreateOrganizationCard | Create a new org with auto-generated slug | | InviteMemberCard | Invite a user by email with role selection | | OrganizationMembersCard | List members, edit roles, remove members | | OrganizationInvitationsCard | View, resend (with cooldown), and revoke pending invitations | | AcceptInvitationCard | Accept or decline an incoming invitation | | OrganizationsCard | Grid/list view of all orgs with leave action | | OrganizationSwitcher | Dropdown to switch the active organization | | OrganizationSettingsView | Orchestrator — renders all org settings sections |

Control and Guard Components

| Component | Description | | --- | --- | | SignedIn | Renders children only when a session exists | | SignedOut | Renders children only when no session exists | | AuthLoading | Renders children while the session is loading | | Protect | RBAC wrapper — accepts role, permission, condition, and fallback props | | RedirectToSignIn | Redirects unauthenticated users to the sign-in page | | RedirectToSignUp | Redirects unauthenticated users to the sign-up page | | UserAvatar | Renders a user avatar image with initials fallback and online status | | SignInButton | Button that triggers sign-in navigation | | SignUpButton | Button that triggers sign-up navigation | | SignOutButton | Button that calls signOut() |

Localization

All components read from a centralized AuthLocalization object (~341 keys). Override any key globally via AuthProvider or per-component via the localization prop:

// Global override on AuthProvider
<AuthProvider
  baseUrl="https://auth.atzentis.com"
  localization={{
    loginForm: {
      title: "Welcome back",
      submitButton: "Continue",
    },
  }}
>

// Per-component override
<LoginForm
  localization={{
    title: "Sign in to Acme",
  }}
/>

Error messages from AuthErrorCode values are automatically localized via getLocalizedError(). Set localizeErrors={false} on AuthProvider to disable this behavior.

Server Entry Point

The default entry point (@atzentis/auth-react) adds a "use client" directive to all exports for React Server Component compatibility. For server-side usage (e.g., reading accountViewSections or organizationViewSections in a layout), import from the server entry:

import {
  accountViewSections,
  organizationViewSections,
} from "@atzentis/auth-react/server";

Peer Dependencies

| Package | Version | | --- | --- | | react | >= 18.0.0 | | react-dom | >= 18.0.0 | | @tanstack/react-query | ^5.0.0 | | @atzentis/ui-shadcn | >= 0.1.0 (optional) | | @atzentis/ui-shared | >= 0.1.0 (optional) |

The UI packages (@atzentis/ui-shadcn, @atzentis/ui-shared) are optional. If not installed, component rendering falls back to unstyled HTML elements.

Related Packages

• @atzentis/auth-sdk — Core TypeScript client (required)
• @atzentis/auth-expo — React Native/Expo screens

License

MIT — see LICENSE for details.