Quickstart — Next.js - Authaz

import { createAuthazHandler } from "@authaz/next";
 
export const { GET, POST } = createAuthazHandler({
  clientId: process.env.AUTHAZ_CLIENT_ID!,
  clientSecret: process.env.AUTHAZ_CLIENT_SECRET!,
  organizationId: process.env.AUTHAZ_ORGANIZATION_ID!,
  tenantId: process.env.AUTHAZ_TENANT_ID,
  afterLoginUrl: "/dashboard",
  afterLogoutUrl: "/",
});

Route	What it does
`GET /api/auth/login`	Redirects to Authaz Sign-In with PKCE.
`POST /api/auth/callback`	Receives the OAuth code, exchanges it, sets the session cookie.
`POST /api/auth/logout`	Clears the session and redirects.
`GET /api/auth/me`	Current user, or `401` if not signed in.
`POST /api/auth/refresh`	Refreshes the access token.

// app/auth/callback/page.tsx
"use client";
 
import { Suspense, useEffect } from "react";
import { useSearchParams } from "next/navigation";
 
const CallbackContent = () => {
  const searchParams = useSearchParams();
 
  useEffect(() => {
    const form = document.createElement("form");
    form.method = "POST";
    form.action = "/api/auth/callback";
 
    ["code", "state", "error", "error_description"].forEach((param) => {
      const value = searchParams.get(param);
      if (value) {
        const input = document.createElement("input");
        input.type = "hidden";
        input.name = param;
        input.value = value;
        form.appendChild(input);
      }
    });
 
    document.body.appendChild(form);
    form.submit();
  }, [searchParams]);
 
  return <p>Completing login…</p>;
};
 
export default function CallbackPage() {
  return (
    <Suspense fallback={<p>Loading…</p>}>
      <CallbackContent />
    </Suspense>
  );
}

// app/layout.tsx
import { AuthazProvider } from "@authaz/react";
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthazProvider basePath="/api/auth" autoRefresh>
          {children}
        </AuthazProvider>
      </body>
    </html>
  );
}

// app/components/AuthButton.tsx
"use client";
 
import { useAuthaz } from "@authaz/react";
 
export const AuthButton = () => {
  const { isAuthenticated, isLoading, user, login, logout } = useAuthaz();
 
  if (isLoading) return <span>…</span>;
 
  return isAuthenticated ? (
    <div>
      <span>{user?.email}</span>
      <button onClick={() => logout()}>Logout</button>
    </div>
  ) : (
    <button onClick={() => login()}>Login</button>
  );
};

// app/api/protected/route.ts
import { withAuth } from "@authaz/next";
import { NextResponse } from "next/server";
 
export const GET = withAuth(async () => {
  return NextResponse.json({ secret: "only signed-in users see this" });
});

{
  isAuthenticated: true,
  isLoading: false,
  user: {
    id: "user_01h...",
    email: "you@example.com",
    name: "Your Name",
    mfaEnabled: false,
    organizations: [{ organizationId: "0199...", accessLevel: "owner" }],
  },
  // login, logout, refresh callbacks
}

Symptom	Likely cause	Fix
Login click → `invalid_request` error page	Redirect URI mismatch.	Confirm `http://localhost:3000/auth/callback` is registered exactly in Settings → Redirect URIs.
Land on `/auth/callback` and see a 404 or blank page	Step 4 callback page missing or has a JS error.	Confirm `app/auth/callback/page.tsx` exists and the form re-POSTs to `/api/auth/callback`.
`useAuthaz()` is stuck on `isLoading: true`	`AuthazProvider` not wrapping the tree, or `basePath` doesn't match the handler route.	Check `app/layout.tsx` wraps `{children}`, and `basePath="/api/auth"` matches the catch-all in Step 3.
Server logs `invalid_client` on token exchange	`AUTHAZ_CLIENT_SECRET` wrong, or you swapped Application ID and Client Secret.	Re-copy from Settings → API Keys.
`401` from `/api/auth/me` after a long idle	Access token expired and refresh failed.	Confirm `autoRefresh` is on and that the refresh token cookie is present.

Quickstart — Next.js

Prerequisites#

Step 1 — Install

Step 2 — Environment variables#

Step 3 — Mount the auth handler#

Step 4 — Add the OAuth callback page#

Step 5 — Wrap the app in `AuthazProvider`#

Step 6 — Use the hooks#

Step 7 — Protect a page#

Step 8 — Protect API routes#

Step 9 — Run it#

If something's wrong#

Going further#

Complete worked example#

Next steps#

Prerequisites#

Step 1 — Install

Step 2 — Environment variables#

Step 3 — Mount the auth handler#

Step 4 — Add the OAuth callback page#

Step 5 — Wrap the app in AuthazProvider#

Step 6 — Use the hooks#

Step 7 — Protect a page#

Step 8 — Protect API routes#

Step 9 — Run it#

If something's wrong#

Going further#

Complete worked example#

Next steps#

Step 5 — Wrap the app in `AuthazProvider`#