@authowl/react

Complete SDK guide · React quickstart · Error handling

React provider, hooks, and drop-in components for AuthOwl, the multi-tenant auth service. Publishable-key based, zero CSS setup.

pnpm add @authowl/react

import { AuthOwlProvider, GoogleOneTap, SignIn, useUser } from '@authowl/react';
import '@authowl/react/styles.css';

function App() {
  return (
    <AuthOwlProvider publishableKey={import.meta.env.VITE_AUTHOWL_PK} apiUrl="https://auth.yourdomain.com">
      <GoogleOneTap />
      <Page />
    </AuthOwlProvider>
  );
}

function Page() {
  const { user, isLoaded, isSignedIn } = useUser();
  if (!isLoaded) return null;
  return isSignedIn ? <p>Hi, {user.email ?? user.phoneNumber}</p> : <SignIn />;
}

Components: <SignIn />, <SignUp />, <PrivacyCenter />, <PhoneOTP />, <SocialButtons />, <MagicLinkForm />, <EmailOtpForm />, <PasskeyButton />, <PasskeyManager />, <ForgotPassword />, <ResetPassword />, <VerifyEmail />, <VerificationPending />, <MFAEnrollment />, <MFAChallenge />, <Waitlist />, <ConsentGate />, <MFARequiredGate />, <PasskeyOfferGate />, <UserButton />, <SignOutButton />, <SignedIn>/<SignedOut>/<Protect>, <AuthOwlBadge />, <UserProfile />, <OrganizationSwitcher />, <OrganizationList />, <CreateOrganization />, <OrganizationProfile />, <GoogleOneTap />.

Hooks: useUser, useSession, useSignIn, useSignUp, useSignOut, usePrivacy, usePasskeys, usePasswordReset, useEmailVerification, useMFA, useConsent, usePublicConfig, useWaitlist.

Wrap your signed-in application in <PasskeyOfferGate> to offer a passkey once, just after someone signs in by another method. It never blocks: children render immediately, and the offer appears only once the checks confirm the user could actually use a passkey - the project allows registration, the page can reach the relying party, the browser supports WebAuthn, the account is not two-factor enrolled, and the server reports no passkey yet. A decline is remembered per browser for thirty days; an enrolment ends the asking.

When the environment's acquisition mode is waitlist, <SignUp /> automatically renders email enrollment instead of account-creation methods. <Waitlist /> is also available as a standalone surface. Both use the same public endpoint, privacy-safe accepted state, and action-bound Turnstile challenge.

When the environment publishes privacy notices, <SignUp /> renders their exact English or Arabic versions and submits immutable delivery evidence with the account-creation request. Optional consent purposes are off by default and are recorded separately from terms acceptance. Signed-in users can use <PrivacyCenter /> to change those choices, withdraw a grant immediately, read current notices, submit data-rights requests, and track request status. The same operations are available headlessly through usePrivacy() or client.privacy from @authowl/core.

The sign-up, sign-in, and account-management components also follow the project's identity lifecycle policy. This includes separate sign-up and sign-in permissions, username sign-in, optional username and first/last-name collection, link or code email verification, passkey registration, email changes, account deletion, and TOTP backup-code availability. Existing credentials remain manageable even when creating another credential of that type is disabled.

Built-in controls use AuthOwl gold (#F5B84C) by default. A project color set in the dashboard replaces it automatically, and an explicit provider override wins over the project setting:

<AuthOwlProvider appearance={{ primaryColor: '#0EA5A4' }} {...config} />

When phone OTP is enabled, <SignIn /> adds the localized phone flow automatically. <PhoneOTP /> is also available as a standalone surface. Production hosts must allow Cloudflare Turnstile's challenge script in their Content Security Policy. Local and CI servers use AuthOwl's documented dummy-token path when no public site key is configured. When the server selects an Akedly Shield V1.2 route, these components fetch a fresh challenge and complete its proof-of-work and optional Turnstile ceremony automatically. Provider API keys and pipeline credentials remain server-side. Custom phone UIs can call phoneOtp.prepare() and solvePhoneOtpChallenge() to implement the same guarded flow. See the complete headless and retry guide.

@akedly/shield is installed with @authowl/core so every consumer bundler can resolve the integration safely. It remains behind a dynamic import, so its browser proof code is loaded only when the server selects a Shield route.

When broad auth protection is enabled, the sign-in, sign-up, magic-link, email OTP, password-reset, and verification components automatically run an action-bound Turnstile challenge. Each attempt receives a fresh single-use token, including retries, and provider failures are announced accessibly in English or Arabic. No extra component wiring is required.

<GoogleOneTap /> reads the enabled Google provider and its public OAuth client id from project config, renders no DOM, and does nothing for an existing session. Hosts with a Content Security Policy must allow Google Identity Services as documented in Google's CSP guide.

Publishable keys (pk_test_… in development, pk_live_… in production) are safe to embed in client code. Durable session tokens live only in HttpOnly + Secure + SameSite=None cookies. useSession() and <UserProfile /> use token-free session ids and safe device metadata.

See the complete React guide for provider configuration, hooks, component contracts, localization, theming, and errors.

License

MIT