@auth-gate/react

React SDK for AuthGate — drop-in authentication with OAuth, email, SMS, and MFA for React apps using Hono as the backend.

Installation

npm install @auth-gate/react

Peer dependencies: react >= 18, hono >= 4

Quick Start

1. Create Auth Routes (Server)

// server/auth.ts
import { createAuthRoutes } from "@auth-gate/react/server";

const auth = createAuthRoutes({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: "https://authgate.dev",
  appUrl: "http://localhost:3000",
});

2. Mount in Hono

// server/index.ts
import { Hono } from "hono";
import { auth } from "./auth";

const app = new Hono();
app.route("/api/auth", auth);

export default app;

3. Add the Provider (Client)

// src/App.tsx
import { AuthProvider } from "@auth-gate/react";

export default function App() {
  return (
    <AuthProvider>
      <Router />
    </AuthProvider>
  );
}

4. Use the Hooks

import { useAuth } from "@auth-gate/react";

function Profile() {
  const { user, loading, logout } = useAuth();

  if (loading) return <p>Loading...</p>;
  if (!user) return <p>Not signed in</p>;

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

Route Map

The Hono router registers these routes under your mount path (e.g. /api/auth/):

| Method | Route | Description | |--------|-------|-------------| | GET | /:provider/login | Start OAuth flow (google, github, discord, azure, apple) | | GET | /callback | OAuth / magic link callback | | POST | /email/signup | Email registration | | POST | /email/signin | Email sign-in | | POST | /email/forgot-password | Request password reset | | POST | /email/reset-password | Confirm password reset | | POST | /email/verify-code | Verify email with OTP | | POST | /magic-link/send | Send magic link | | POST | /sms/send-code | Send SMS code | | POST | /sms/verify-code | Verify SMS code | | POST | /mfa/verify | Complete MFA challenge | | POST | /refresh | Refresh session token | | POST | /logout | Sign out and revoke session | | GET | /me | Get current user |

Client Components

<AuthProvider>

Wraps your app and manages auth state via context.

<AuthProvider
  meEndpoint="/api/auth/me"       // default
  logoutEndpoint="/api/auth/logout" // default
>
  {children}
</AuthProvider>

| Prop | Type | Default | Description | |------|------|---------|-------------| | meEndpoint | string | "/api/auth/me" | Endpoint to fetch current user | | logoutEndpoint | string | "/api/auth/logout" | Endpoint to call on logout |

<AuthGuard>

Protects routes by redirecting unauthenticated users.

import { AuthGuard } from "@auth-gate/react";

function ProtectedPage() {
  return (
    <AuthGuard redirectTo="/login" loadingFallback={<Spinner />}>
      <Dashboard />
    </AuthGuard>
  );
}

| Prop | Type | Default | Description | |------|------|---------|-------------| | redirectTo | string | "/login" | Redirect path when not authenticated | | loadingFallback | ReactNode | — | Shown while session is loading |

Hooks

useAuth()

Returns the full auth context.

const { user, loading, refresh, logout } = useAuth();

| Property | Type | Description | |----------|------|-------------| | user | AuthGateUser \| null | Current user or null | | loading | boolean | True while fetching session | | refresh | () => Promise<void> | Re-fetch the session | | logout | () => Promise<void> | Sign out and clear state |

useSession()

Shorthand that returns just the user.

const user = useSession(); // AuthGateUser | null

Authentication Examples

OAuth Sign-In

<a href="/api/auth/google/login">Sign in with Google</a>
<a href="/api/auth/github/login">Sign in with GitHub</a>

Email Sign-In

const res = await fetch("/api/auth/email/signin", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password }),
});

const data = await res.json();

if (data.mfa_required) {
  await fetch("/api/auth/mfa/verify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      mfa_challenge: data.mfa_challenge,
      code: totpCode,
      method: "totp",
    }),
  });
}

SMS Sign-In

await fetch("/api/auth/sms/send-code", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ phone: "+15551234567" }),
});

await fetch("/api/auth/sms/verify-code", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ phone: "+15551234567", code: "123456" }),
});

Server API Reference

createAuthRoutes(options)

Creates a Hono router with all auth endpoints.

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | AuthGate API key (also used to resolve project ID) | | baseUrl | string | Yes | AuthGate instance URL | | appUrl | string | Yes | Your app's URL | | cookieName | string | No | Cookie name (default: __authgate) | | sessionMaxAge | number | No | Session TTL in seconds (default: 604800) | | callbackPath | string | No | Callback path (default: /api/auth/callback) |

Types

import type { AuthGateUser, OAuthProvider } from "@auth-gate/react";

Re-exported from @auth-gate/core for convenience.

License

MIT