Passwordless authentication with React JS

‍TL;DR:

• Hook-based state machine: ^{usePasswordlessAuth} encapsulates all phases (idle → sending → codeSent → verifying → authenticated → error) so React components stay declarative and reusable.
• Server-first security: Scalekit issues and validates cryptographically signed tokens with expiry, origin binding, and resend invalidation; secrets never touch the client.
• Reusable components: ^EmailForm, ^OtpForm, and ^{MagicLinkHandler} consume hook state directly, handling edge cases (expired codes, double clicks, redirects) without ad-hoc logic.
• Persistent context: ^AuthProvider hydrates sessions on mount, persists state across reloads, and centralizes access so routes only check phase === "authenticated".
• Resilient UX: explicit loading states, error boundaries, auto-submit OTPs, and countdown timers prevent frozen screens and remove friction for users.
• Type-safe + testable: TypeScript enforces complete phase coverage, and Vitest + Testing Library replay real failure modes (resends, expiry, refreshes) to prevent regressions.

A mid-size product team decided to modernize their login experience by replacing passwords with email-based links and short codes. The idea seemed simple: remove the burden of forgotten passwords while giving users a smoother way to sign in. But as they started building it in React, the complexity quickly surfaced. Multiple forms had to be managed, asynchronous calls collided with redirects, and state became fragile when users switched tabs or devices. What began as a small feature turned into tangled code that was hard to maintain and nearly impossible to reuse across different parts of the app.

The real issue was not in the authentication methods themselves, but in how the frontend managed them. Scalekit provides secure APIs for issuing and validating credentials, but without a clear way to structure the React side, teams often end up reinventing state machines and temporary fixes. By shifting to a hook-based pattern and centralizing authentication state in context, React developers can treat login as a reusable set of components rather than scattered logic. Hooks handle inputs, link detection, and verification, while context ensures the app always knows whether a user is signed in.

This guide shows how to build production-ready React components for passwordless authentication using the Scalekit SDK. You will learn how to create a custom authentication hook, implement email and code input components with validation, handle magic link redirects automatically, persist authentication state with context, and integrate loading states, error boundaries, and type safety. The result is a complete authentication flow that works reliably across projects and scales without added complexity. You can explore the full working project that this guide is based on in our GitHub repository: React Passwordless Authentication Example.

At a high level, passwordless authentication is just: collect email → issue credential → verify → authenticate.

Why passwordless authentication matters

Passwords remain the default login method in most applications, yet they introduce constant problems. From a security standpoint, static secrets stored in databases are prime targets for leaks and credential stuffing attacks. From a user standpoint, password resets are one of the most common sources of friction, leading to weak adoption or churn. Engineering teams often spend time building reset flows, implementing rate limiting, and monitoring suspicious login activity, all of which divert attention from product work.

Passwordless authentication eliminates stored secrets by using short-lived, verifiable credentials. The two most common approaches are magic links and one-time passcodes (OTP). A magic link encodes a signed, expiring token inside a URL. When the user clicks it, the client submits the token back to the server for verification. An OTP works the same way but delivers a short numeric code instead of a link, which provides a fallback when links expire or when users switch devices mid-session. Both methods reduce exposure because tokens expire quickly and cannot be reused.

For frontend teams, the implications are significant. Login becomes a matter of collecting an email, handling a redirect, and submitting either a link token or a numeric code. There is no need for password strength checks, hashing libraries, or reset UIs. What’s left is a cleaner surface area for React developers to implement reusable components that guide the user through these flows, while the backend enforces the actual security guarantees.

The role of Scalekit in the architecture

Passwordless authentication only works if the issuing and validation of credentials are secure. In a typical custom setup, teams need to build their own token generator, manage expirations, prevent replay attacks, and handle resend logic. These rules live on the server and must be enforced consistently across environments. Any gap in implementation, such as weak signing, missing expiry checks, or improper storage, turns into a critical vulnerability.

Scalekit provides an API-first model for handling this layer. It issues cryptographically signed tokens, enforces expiry windows, and validates them without exposing secrets to the client. Features like same-browser binding prevent tokens from being replayed on different devices, and resend handling ensures that only the most recent link or code is valid. Instead of embedding this logic inside a React app, developers call Scalekit’s endpoints from the server, which keeps secrets confined to environment variables.

With this separation, React can focus entirely on the frontend flow: collecting the user’s email, detecting when a magic link is clicked, verifying a code, and maintaining authentication state. Scalekit guarantees that the underlying tokens are valid, short-lived, and resistant to replay. This division of responsibilities makes the architecture both cleaner and more secure.

The frontend only orchestrates UI and state, while Scalekit enforces token security on the server

Setting up a fresh React + Scalekit passwordless project

You don’t need to start from an existing repo. The flow in this guide can be built from scratch using a React frontend and a TypeScript Express backend that talks to Scalekit.

1. Initialize the project structure

2. Create the frontend (React 18 + Vite + TypeScript):

3. Create the backend (Express + TypeScript):

4. Install Scalekit SDK in the backend

5. Set up environment variables in ^server/.env:

6. Run both servers in parallel

7. Open the app at http://localhost:5173.

At this point you’ll have a blank canvas: a React app ready to integrate the ^{usePasswordlessAuth} hook, and an Express backend wired to Scalekit to issue and verify credentials. The sections that follow will fill in both sides step by step.

Designing React for authentication flows

React applications excel at building interactive interfaces, but authentication flows often stretch the limits of ad-hoc state management. A login flow requires tracking form inputs, pending requests, redirects from magic links, verification of codes, and the user’s final authenticated state. If each of these is handled directly inside components, the result is duplicated logic, race conditions, and components that are difficult to reuse.

The React model already provides the right primitives to manage this complexity. Hooks encapsulate logic like sending login requests or validating a one-time code, so components stay focused on rendering. Context supplies a shared authentication state across the tree, ensuring every part of the app can react to sign-in or sign-out without prop drilling. Together, hooks and context form a reliable pattern: hooks handle side-effects and state transitions, while context exposes a single source of truth for whether a user is authenticated.

For passwordless authentication, this pattern is especially powerful. The same hook can issue both magic links and OTPs, while context keeps track of whether a user has completed verification. React components simply consume these hooks and context values, making the login experience portable across pages or even projects. This approach avoids fragile state machines and keeps authentication logic isolated, tested, and reusable.

A minimal ^{usePasswordlessAuth} hook (state machine+handlers)

This core excerpt makes the state machine explicit and shows the exact handlers the components consume. It mirrors the phases used throughout the article and keeps external concerns (cookies, storage) behind the hook boundary.

The hook encodes the login process as a state machine with predictable transitions.

Why this helps the reader: it crystallizes the state machine (^{idle → sending → codeSent → verifying → authenticated → idle/error}), shows the exact network boundaries, and demonstrates persistence, countdown, and deduping in a compact, production‑ready pattern.

Building an email input component with clear validation and resilient UX

Email capture is the first place our SaaS team’s flow used to break. The form must trim input, validate format, prevent duplicates while sending, and surface backend errors without leaking whether an email exists. In your project, ^{EmailForm.tsx} calls ^{useAuth().send(email)} and persists the authRequestId via the hook, so the component’s job is strict input handling and a clean pending state that maps to the hook’s phase: "sending".

Validation rules that avoid brittle edge cases

• Format validation uses a pragmatic regex (not full RFC), after ^{trim().toLowerCase().}
• Disabled submit during ^{phase === "sending"} prevents double posts.
• Generic success copy (“Check your email for a link or code”) avoids account enumeration.
• Accessible markup uses a ^<label>, ^aria-invalid, and ^{aria-describedby} for errors.
• Error surfacing renders the error from the hook without exposing server internals.

How this tie back to the scenario

Form duplication and race conditions were pain points for the team. This component routes all network work to the hook, reads a single phase flag to gate UI, and never guesses server state. The result is a reusable, portable form that behaves identically on every page and supports both magic links and codes without branching logic in the component.

Implementing a resilient one-time code verification component with auto-submit

OTP verification used to be the team’s most brittle screen. Focus jumps, paste glitches, and expired codes stranded users. This version treats verification as a pure UI over the hook’s ^{codeSent → verifying → authenticated} phases. The component manages six digit boxes, paste-to-fill, auto-submit on completion, and a live countdown sourced from the hook’s ^timeLeft. The form never guesses server state; it only calls ^{verifyCode(code)} and renders phase and error.

Behavior the component guarantees

• Six inputs accept only digits; backspace moves focus left; typing moves right.
• Pasting a full code distributes digits across boxes in one step.
• Auto-submit triggers once all boxes are filled; manual submit remains available.
• Countdown reads timeLeft; an expired code disables inputs and shows recovery.
• Accessibility uses labels, ^aria-invalid, and ^aria-live for the timer.

How this ties back to the scenario

The team’s earlier OTP screen chained timers and disabled inputs unpredictably after redirects. This version lets the hook own the countdown and expiry cleanup, while the component only reflects ^{active/pending/expired}. Paste-to-fill fixes “copy-from-email” friction, and auto-submit eliminates the extra click, two small changes that removed most support tickets around code entry.

Detecting magic link tokens on redirect and verifying safely

Magic link redirects are the most timing‑sensitive step our team faced. Redirects land the user on an app route with a ^link_token (and sometimes ^{auth_request_id}) in the query string. The UI should verify immediately, avoid double posts when users re‑click the email, and then clean up the URL. Your hook already implements deduping and same‑browser binding via the persisted request id, so the component’s role is to extract parameters, call handleMagicLink, and render progress or recovery states.

Magic links are automatically consumed on redirect, deduped, and the URL is cleaned up to prevent replay

Implementation that is resilient and idempotent

How this maps to the real scenario

Magic links previously caused duplicate submissions when users double‑clicked or refreshed. The hook’s token cache stops concurrent verifies, while the handler removes query parameters to prevent accidental replays. Origin binding is preserved by passing auth_request_id when present and falling back to the stored value in the hook. The end result mirrors the team’s goal: instant verification on arrival, predictable states (verifying → authenticated | error), and a clean URL that won’t surprise support or users.

Providing application-wide authentication state and persistence

Global state solved our team’s duplicate logic. Instead of each screen inferring whether the user is signed in, a single context exposes phase, email, and actions from the hook. Your AuthProvider wraps the tree and offers useAuth() as the only interface. The hook performs session hydration on mount by calling /auth/passwordless/session; if a cookie session exists, it immediately promotes the app to authenticated. Local storage persists authRequestId, the last sendResult, and a session email, so reloads and route changes don’t reset the flow.

^AuthProvider centralizes state, so routes only need to check one flag: authenticated or not.

Route protection with declarative, testable gates

Why this fixes the scenario’s pain points

The team’s earlier approach mixed ad‑hoc checks and duplicated fetches across screens, producing races after redirects. Centralizing the state eliminates those races: only the hook talks to the backend, only the provider publishes state, and only gates decide what to render. Persistence prevents users from getting stuck between email send and verification, and the session bootstrap upgrades returning users without flashing the login. The result is a consistent, portable authentication surface that scales with new routes and layouts.

Handling loading states and error boundaries for predictable UX

The team’s old flow caused confusion for users whenever issues arose, spinners froze, error messages disappeared upon refresh, and the app occasionally crashed mid-verify. Two patterns fix this: explicit loading states tied to the hook’s phase, and a global error boundary that catches unexpected runtime errors. Together, they ensure that authentication UI never leaves the user without feedback.

Explicit loading and error surfaces

Each UI component maps phases into concrete messages or spinners. For example:

• ^{phase === "sending"} → disable form and show “Sending link…”
• ^{phase === "verifying"} → show progress bar while awaiting backend
• ^{phase === "error"} → render error string, with a restart option

This approach guarantees every async branch has a visible outcome.

Global error capture with boundaries

Wrapping the entire app in ^{AppErrorBoundary} ensures that if a logic bug slips through, say, a malformed JSON response, the app shows a recoverable error instead of a blank screen.

Back to the scenario

Where the team once saw blank states or unresponsive forms, users now always see a spinner, a countdown, or a retry option. Even unhandled errors degrade gracefully, protecting the authentication experience and avoiding the support churn that plagued their first attempt.

Enforcing type safety with TypeScript across all authentication flows

In the team’s first attempt, missing checks for edge states caused silent failures, expired codes weren’t cleared, and UI components incorrectly assumed the user was authenticated. By encoding states and API responses in TypeScript, those gaps become compiler errors instead of runtime surprises.

Defining explicit auth phases and API shapes

Every component consumes ^{phase: PasswordlessPhase}, which forces a switch or conditional to cover all possibilities. When the hook adds a new phase, the compiler prompts updates in every consumer.

Typing hook return values for context safety

The ^AuthProvider context then exposes ^{PasswordlessAuth}, ensuring every component that calls ^useAuth() gets full intellisense and can’t mis-type function calls.

How this solved the scenario’s pain points

The team’s early React prototype failed silently when the backend changed a response shape. With explicit ^SendResult and ^{PasswordlessPhase}, those errors now surface as compile-time breaks. Developers can add flows confidently, knowing unhandled cases will be flagged by the compiler instead of reaching production.

Testing patterns and mocking strategies for reliable passwordless flows

Automated tests prove that the flow survives redirects, expired codes, and double‑clicks, the exact failure modes from our scenario. Unit tests target the hook’s state machine; component tests cover input behavior, countdowns, and URL handling. Vitest runs the suite with a JSDOM environment, while Testing Library simulates user interaction. Network calls are mocked by stubbing global.fetch; timers are controlled with vi.useFakeTimers() to advance expiries deterministically. Local storage is shimmed so hydration and cleanup logic can be asserted without a browser.

What to mock and why

• ^fetch → return shaped JSON for ^/send, ^/verify-code, ^/verify-link, ^/session, ^/logout.
• ^Date.now() or ^timers → advance ^expiresAt countdowns and trigger auto‑clear paths.
• ^localStorage → seed ^{pl.sendResult} and ^{pw_auth_request_id}, then assert cleanup.
• ^{window.location} and ^{history.replaceState} → emulate magic link redirects and cleanup.

Hook tests validate phases and edge cases

Component tests simulate user paths from the story

• EmailForm → type invalid then valid email, assert disabled/enabled submit, assert ^sending lock.
• OtpForm → paste six digits, auto‑submit, assert ^{verifying → authenticated}; advance timers to force expiry and assert reset UI.
• MagicLinkHandler → set ^{?link_token=...} in ^{window.location}, assert ^verifying, then ^success; verify query params are removed via ^{history.replaceState}.
• Session bootstrap → mock /session returning ^{{ authenticated: true, email }}, render provider only, and assert immediate authenticated without flicker.

These tests prevent regressions where the team once struggled: duplicate requests, racey countdowns, and brittle redirects. The suite locks in the desired behavior, so refactors to the hook or UI can proceed with confidence.

These tests replay the exact failure modes from our scenario, including double-click resends, racey countdown expiries, and magic-link refreshes, so the suite proves the refactor eliminates the issues that originally made the flow brittle.

Bringing it all together: production-ready passwordless authentication in React

What started as a messy React prototype, full of duplicated state, brittle redirects, and endless password resets, has been reshaped into a production-ready flow that is both secure and reusable. By structuring the frontend around a ^{usePasswordlessAuth} hook and global AuthProvider, and letting Scalekit enforce token issuance and verification on the backend, the SaaS team in our story went from firefighting login bugs to shipping a flow they can actually trust.

The pieces now work together cleanly:

• Scalekit + Express API: issues and validates short-lived credentials with expiry and origin guarantees.
• React 18 + TypeScript: encapsulates client-side complexity in predictable hooks and contexts.
• Reusable components: ^EmailForm, ^OtpForm, and ^{MagicLinkHandler} declaratively render progress, errors, and edge states without ad-hoc logic.
• Resilient UX and testing: error boundaries, typed phases, and Vitest suites lock in behavior and prevent regressions.

The result maps directly back to the original pain points: magic links validate once, OTPs expire predictably, sessions persist across reloads, and users never see a frozen screen. What was once fragile boilerplate is now a portable authentication layer that can be dropped into future React projects without repeating old mistakes.

If you’re building modern authentication flows, the next steps are clear:

• Clone the full working project from GitHub to see the implementation in action.
• Read deeper into related topics, server-side session hardening, cross-origin replay protection, or advanced testing patterns for auth.
• Try Scalekit in your own project to offload token security and focus on building great user experiences.

Authentication doesn’t have to be the most painful part of your stack. With React hooks for state and Scalekit for security, passwordless login becomes not just possible, but practical and production-ready.

FAQ

How does Scalekit enforce magic link origin binding in passwordless authentication?

Scalekit pairs each issued token with an authRequestId that is bound to the originating browser session. When the React app calls ^/verify-link, the SDK checks that the provided token matches both the request and its original client context, preventing token replay across devices.

Can Scalekit passwordless authentication handle multiple resend requests safely?

Yes. Scalekit enforces both credential freshness and rate limiting. When a new OTP or magic link is issued, the previous ^{authRequestId} is invalidated, so only the most recent credential can succeed. On top of that, the ^/send and ^/resend endpoints are capped at 2 passwordless emails per minute per address, and the ^/verify endpoint allows only five OTP attempts within ten minutes. These safeguards prevent credential spamming and brute-force guessing while keeping the flow reliable for legitimate users.

Why use a custom React hook for passwordless authentication instead of Redux or Zustand?

A hook tightly couples state transitions (^{idle → sending → codeSent → verifying → authenticated}) with side-effects like API calls and ^localStorage hydration. This keeps authentication logic isolated, prevents global store bloat, and lets components stay declarative by consuming only what they need.

How should OTP expiry and countdown be implemented in React without memory leaks?

Use ^useEffect with a ^setInterval tied to the OTP’s ^expiresAt value. On unmount or expiry, clear the interval. This approach ensures countdown timers don’t accumulate across re-renders and guarantees React’s cleanup cycle prevents memory leaks.

What are the best practices for testing passwordless flows in React with Vitest?

Mock fetch responses for ^/send, ^/verify-code, ^/verify-link, and ^/session endpoints. Control time with ^{vi.useFakeTimers()} to simulate code expiry. Simulate paste-to-fill in OTP forms using Testing Library events. These patterns validate the full state machine without needing a live backend.