Quickstart

Get up and running with AuthGate in under 5 minutes. This guide walks you through creating a project, enabling providers, and authenticating your first user with OAuth, email/password, or SMS.

Create a project

Log in to the AuthGate dashboard and create a new project. Give it a name that identifies your application.

Once created, you'll land on the project overview page where you can configure providers, callback URLs, and API keys.

Enable providers

Navigate to the Providers tab and enable the authentication methods you need.

OAuth providers

For a quick start, GitHub is the easiest to set up:

  1. Go to GitHub Developer Settings and create a new OAuth App
  2. Set the Authorization callback URL to {AUTHGATE_URL}/api/proxy/callback/github
  3. Copy the Client ID and Client Secret into the AuthGate dashboard

Email/password

Enable the Email provider in the Providers tab. This gives your users email sign-up, sign-in, forgot-password, and reset-password flows. See Email Auth for email infrastructure setup.

SMS verification

Enable the SMS provider for passwordless phone authentication. Users receive a 6-digit verification code via SMS. See SMS Auth for provider configuration.

Register a callback URL

Go to the Callbacks tab and add the URL where AuthGate should redirect users after authentication. For example:

http://localhost:3000/api/auth/callback

Create an API key

Navigate to the API Keys tab and create a new key. Copy the key now, or reveal it later from the dashboard using the eye icon. You'll use this key to verify tokens server-side.

Integrate with your app

Choose your approach: the SDK handles sessions, state, and route protection for you, while the Custom approach gives you full control over every detail.

Option A: SDK (recommended)

Next.js

Install the SDK:

pnpm add @auth-gate/nextjs

Set up environment variables:

.env.local

AUTHGATE_API_KEY=your-api-key
AUTHGATE_URL=https://your-slug.authgate.dev
NEXT_PUBLIC_APP_URL=http://localhost:3000

Initialize the SDK in a single file:

src/lib/auth.ts

import { createAuthGate, createAuthGateMiddleware } from "@auth-gate/nextjs";

const appUrl = process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";

function getAuth() {
  return createAuthGate({
    apiKey: process.env.AUTHGATE_API_KEY!,
    baseUrl: process.env.AUTHGATE_URL!,
    appUrl,
  });
}

let _auth: ReturnType<typeof getAuth> | null = null;
function auth() {
  if (!_auth) _auth = getAuth();
  return _auth;
}

export const handlers = {
  GET: (...args: Parameters<ReturnType<typeof getAuth>["handlers"]["GET"]>) =>
    auth().handlers.GET(...args),
  POST: (...args: Parameters<ReturnType<typeof getAuth>["handlers"]["POST"]>) =>
    auth().handlers.POST(...args),
};

export async function getSession() {
  return auth().session.getSession();
}

export const authMiddleware = createAuthGateMiddleware(
  () => auth().client,
  { matcher: ["/dashboard/:path*"], loginPath: "/login" }
);

Create the catch-all route — this single file handles OAuth, email, SMS, sessions, and logout:

src/app/api/auth/[...authgate]/route.ts

import { handlers } from "@/lib/auth";

export const { GET, POST } = handlers;

React (Vite + Hono)

Install the SDK:

pnpm add @auth-gate/react react-router hono @hono/node-server

Set up environment variables:

.env

AUTHGATE_API_KEY=your-api-key
AUTHGATE_URL=https://your-authgate-instance.com
VITE_AUTHGATE_URL=https://your-slug.authgate.dev
VITE_APP_URL=http://localhost:3005

Set up the Hono server with SDK auth routes:

src/server/index.ts

import { serve } from "@hono/node-server";
import { Hono } from "hono";
import { createAuthRoutes } from "@auth-gate/react/server";

const authRoutes = createAuthRoutes({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: process.env.AUTHGATE_URL!,
  appUrl: process.env.VITE_APP_URL || "http://localhost:3005",
});

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

Wrap your app with AuthProvider and AuthGuard:

src/App.tsx

import { BrowserRouter, Routes, Route } from "react-router";
import { AuthProvider, AuthGuard } from "@auth-gate/react";

export default function App() {
  return (
    <BrowserRouter>
      <AuthProvider>
        <Routes>
          <Route path="/login" element={<Login />} />
          <Route path="/signup" element={<Signup />} />
          <Route path="/phone-login" element={<PhoneLogin />} />
          <Route path="/dashboard" element={
            <AuthGuard><Dashboard /></AuthGuard>
          } />
        </Routes>
      </AuthProvider>
    </BrowserRouter>
  );
}

Option B: Custom (full control)

If you prefer to handle sessions and token verification yourself, see the full integration snippets on your project's dashboard page, or the scaffolds documentation.

The custom approach requires you to:

  1. Build API routes that proxy requests to AuthGate (OAuth login, callback, email sign-in/up, SMS send/verify)
  2. Verify tokens server-side using the /api/v1/token/verify endpoint
  3. Manage sessions yourself (HMAC-signed cookies, middleware, etc.)

Add authentication pages

All auth pages work the same way regardless of SDK or custom approach — they call your /api/auth/* endpoints.

Email sign-in

async function handleEmailSignIn(email: string, password: string) {
  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 (!res.ok) throw new Error(data.error);

  window.location.href = data.redirect || "/dashboard";
}

Email sign-up

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

  const data = await res.json();
  if (!res.ok) throw new Error(data.error);

  window.location.href = data.redirect || "/dashboard";
}

SMS verification (two-step)

// Step 1: Send code
async function sendCode(phone: string) {
  const res = await fetch("/api/auth/sms/send-code", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ phone }),
  });
  if (!res.ok) throw new Error((await res.json()).error);
}

// Step 2: Verify code
async function verifyCode(phone: string, code: string) {
  const res = await fetch("/api/auth/sms/verify-code", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ phone, code }),
  });

  const data = await res.json();
  if (!res.ok) throw new Error(data.error);

  window.location.href = data.redirect || "/dashboard";
}

OAuth login

// Redirect to your auth route — it handles the provider redirect
<a href="/api/auth/github/login">Sign in with GitHub</a>
<a href="/api/auth/google/login">Sign in with Google</a>

Next steps

Was this page helpful?