Logout

Logout clears Blueprint-managed authentication cookies in the current browser. Use a Server Action in App Router, or useLogout with an API route in Pages Router. These examples use the exports from the App Router setup and Pages Router setup.

Add a logout button

App Router

Call logout inside a Server Action, not while rendering a Server Component. This form needs neither an API route nor React Query:

app/components/logout-form.tsx

import { logout } from "@/lib/auth/server";

export function LogoutForm() {
  async function logoutAction() {
    "use server";
    await logout();
  }

  return (
    <form action={logoutAction}>
      <button type="submit">Log out</button>
    </form>
  );
}

Keep this component server-side. The action redirects to your configured home page after logout.

If you need the client hook instead, configure the client exports and providers from the setup guide, then expose a Route Handler:

app/api/auth/logout/route.ts

import { createLogoutHandler } from "@krakentech/blueprint-auth/server";
import { authConfig } from "@/lib/auth/config";

export const POST = createLogoutHandler(authConfig);

Use the Pages Router tab's button in a file with "use client" at the top. The same API request requirements below apply.

Pages Router

Create the API route at the path configured by apiRoutes.logout:

pages/api/auth/logout.ts

import { createLogoutHandler } from "@krakentech/blueprint-auth/server";
import { authConfig } from "@/lib/auth/config";

export default createLogoutHandler(authConfig);

Render the button under the setup guide's AuthProvider and QueryClientProvider. The hook sends the request and handles navigation:

components/logout-button.tsx

import { useLogout } from "@/lib/auth/client";

export function LogoutButton() {
  const logout = useLogout();

  return (
    <div>
      <button type="button" disabled={logout.isPending} onClick={() => logout.mutate()}>
        {logout.isPending ? "Logging out…" : "Log out"}
      </button>
      {logout.isError && <p role="alert">Logout failed. Please try again.</p>}
    </div>
  );
}

Redirects

Both logout and useLogout accept nextPage:

• Omit it to use appRoutes.home.pathname, localized when configured.
• Set it to an app path such as "/login" to choose the destination.
• Set it to null to skip the success redirect: await logout({ nextPage: null }) or useLogout({ nextPage: null }). Update the signed-out UI yourself.

Redirects are limited to safe, same-origin destinations. An unsafe or invalid destination produces no redirect rather than sending the user to another site.

The API handler returns JSON containing data.redirectUrl by default; the hook uses that URL to navigate. Direct API callers can send enableRedirect: true for an HTTP redirect instead. The hook does not need this option.

API request requirements

createLogoutHandler accepts POST, not GET, and requires Content-Type: application/json. useLogout sends this automatically. Do not link to the logout endpoint or submit a plain HTML form directly to it.

Configure validation.allowedRequestOrigins or ALLOWED_REQUEST_ORIGINS with trusted app origins, including the scheme and any port. Each request must have an Origin or Referer header; when both are present, both must be trusted. See trusted request origins for configuration examples.

The Server Action form does not call this handler or run its JSON/origin validation. It uses Next.js Server Action request protections instead. Blueprint's API origin allowlist does not configure Next.js Server Action origin checks.

Cookies and client state

When an OAuth ID-token cookie is present, logout first attempts Kraken OAuth logout, then refresh-token revocation if a refresh token is available and the upstream logout succeeds. Upstream network or service failures are best effort: they are logged, and local cookie cleanup still runs.

Configuration or customization errors still propagate after cleanup is attempted. Cookie lookup or removal failures can prevent complete local logout; do not report these as success.

Only a successful useLogout mutation invalidates the session query and then clears its entire React Query client cache. A Server Action or direct API call does not clear that browser cache. If you use either alongside cached private client data, arrange your own cleanup, especially when staying on the page.

Error handling

The Server Action example lets errors propagate. If you add a try/catch, do not swallow Next.js redirect errors: call unstable_rethrow(error) from next/navigation before handling application errors on Next.js 15+. See the setup guide's redirect handling and its Next.js 14 compatibility notes.

By default, a hook failure replaces the current URL with an error query parameter. nextPage: null disables only the success redirect. To customize this behavior, pass onLogoutError to AuthProvider; its onLogoutSuccess prop customizes successful navigation. These callbacks receive a function for default navigation. Call it if you want to retain that navigation behavior. See useLogout.

Security considerations

Clearing cookies ends this browser's local session; it does not guarantee that every previously issued JWT is revoked or that every device is signed out. OAuth revocation depends on the upstream service and is best effort. Continue to enforce token verification and expiry on protected requests; logout is not a substitute for those checks.