React Hooks
AuthCore hooks reference
Every hook below is exported directly from codalware-auth—no sub-path imports required. Copy the snippets into your project and wire them to your AuthCore API routes.
useAuthPolicy(options?: { tenantDomain?: string; debounce?: number; enabled?: boolean })
Streams the current authentication policy from `/api/auth/policy`, normalising tenant domains, debouncing fetches, and exposing manual refresh.
- Normalises tenant domains to lowercase, trimming whitespace before issuing the request.
- Requests are debounced by default (350 ms); pass `debounce: 0` for immediate fetches.
- Returns `refresh()` so forms can re-fetch policy after registration or tenant switches.
useAuth(requireAuth?: boolean)
Reads the NextAuth session, returns the normalized AuthCore user, and exposes helpers for the core role checks.
- Pass `true` to automatically redirect unauthenticated visitors to `/auth/login`.
- `hasRole`, `isSuperAdmin`, `isTenantAdmin`, and `isUser` helpers mirror the server role enums.
- Combines `isAuthenticated` and `isLoading` flags from NextAuth so you can branch UI quickly.
useLogin()
Handles credential sign-in, running the `/api/auth/check-2fa` preflight before delegating to NextAuth.
- Performs the `/api/auth/check-2fa` probe before calling `signIn()` so you can branch into a token prompt gracefully.
- Returns `{ success, error, requiresTOTP }` so you can gate the next UI step.
useRegister()
Posts registration payloads to `/api/auth/register` and returns the policy-driven follow-up steps (verify email, setup 2FA, approval).
- Returns `{ success, data, message, error, errorCode }` where `data.steps` lists follow-up actions to render in the UI.
- Each step mirrors what the modal AuthForm shows—use the same payload to keep standalone flows in sync.
- Leave room to collect `tenantDomain` when onboarding tenant administrators.
useMagicLink()
Queues passwordless login emails and exposes the request lifecycle state.
- Hits `/api/auth/magic-link` with the provided email and surfaces friendly error state.
- Combine with feature toggles to respect tenant and user-level passwordless policies.
useTwoFactor()
Loads the user’s 2FA status and exposes helpers to initiate, verify, and disable TOTP.
- `status` includes `enabled`, and when setup starts it contains `qrCode`, `secret`, and one-time backup codes.
- `verify(token)` finalizes setup and refreshes the session so the UI reflects the new security state.
useUserDevices()
Lists trusted devices and supplies helpers to revoke stale sessions.
- Calls `/api/user/devices` under the hood and keeps the list in sync as you revoke devices.
useAuditLogs(limit?: number)
Streams audit entries for the signed-in user or tenant so you can surface recent security actions.
- Great for tenant admin dashboards so security teams can drill into recent activity without leaving the product.
useUserProfile()
Fetches and updates the profile document for the current user with optimistic helpers.
- Maintains local loading state so you can show optimistic UI before the refreshed data returns.
usePasswordChange()
Wraps the `/api/user/password` endpoint with success and error handling for inline forms.
- Handles optimistic UI for the `success` flag and exposes any server validation errors in `error`.