Use AuthProvider, useAuth, and createAuthClient to add cookie-based AuthInGo sessions to React and Next.js.

React SDK

The @authingo/react package is a headless client for AuthInGo. It does not render UI. It gives you a provider for session state and a small client for calling the Go auth routes.

Install

npm install @authingo/react

pnpm add @authingo/react

yarn add @authingo/react

AuthProvider

Wrap your app with AuthProvider and pass the base URL where your Go auth routes are mounted.

app/providers.tsx

"use client";

import { AuthProvider } from "@authingo/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AuthProvider baseURL="http://localhost:8080/api/auth">
      {children}
    </AuthProvider>
  );
}

Client component required

AuthProvider stores React state and must run in a client component.

Use it from your Next.js root layout:

app/layout.tsx

import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

useAuth

useAuth reads the current session state from the nearest provider.

const { user, isLoading, error, checkSession, logout } = useAuth();

Value	Type	Description
`user`	`User \| null`	The current authenticated user.
`isLoading`	`boolean`	`true` while the provider checks `/session`.
`error`	`string \| null`	The latest session error.
`checkSession`	`() => Promise<void>`	Re-fetches the current session from the backend.
`logout`	`() => Promise<void>`	Calls `/sign-out` and clears local user state.

createAuthClient

Use createAuthClient to call sign in, sign up, and sign out routes.

lib/auth-client.ts

import { createAuthClient } from "@authingo/react";

export const authClient = createAuthClient({
  baseURL: "http://localhost:8080/api/auth",
});

The client exposes:

Method	Calls	Input
`authClient.signIn.email()`	`POST /sign-in`	`{ email, password }`
`authClient.signUp.email()`	`POST /sign-up`	`{ email, password, name }`
`authClient.signOut()`	`POST /sign-out`	none
`authClient.useSession()`	`GET /session`	none

useSession() is a client-side convenience hook for apps that prefer a single client module:

lib/auth-client.ts

import { createAuthClient } from "@authingo/react";

export const authClient = createAuthClient({
  baseURL: "http://localhost:8080/api/auth",
});

export const { signIn, signUp, signOut, useSession } = authClient;

The hook returns { data, isPending, error, refetch }. The provider and client hooks both listen for cross-tab logout messages so another open tab clears its local auth state immediately.

app/login.tsx

"use client";

import { createAuthClient, useAuth } from "@authingo/react";

const authClient = createAuthClient({
  baseURL: "http://localhost:8080/api/auth",
});

export function Login() {
  const { user, isLoading, error, checkSession, logout } = useAuth();

  if (isLoading) return <div>Loading...</div>;

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

  return (
    <div>
      {error ? <p>{error}</p> : null}
      <button
        onClick={async () => {
          const result = await authClient.signIn.email({
            email: "test@example.com",
            password: "password",
          });

          if (!result.error) {
            await checkSession();
          }
        }}
      >
        Sign in
      </button>
    </div>
  );
}

app/sign-up.tsx

"use client";

import { createAuthClient, useAuth } from "@authingo/react";

const authClient = createAuthClient({
  baseURL: "http://localhost:8080/api/auth",
});

export function SignUp() {
  const { checkSession } = useAuth();

  return (
    <button
      onClick={async () => {
        const result = await authClient.signUp.email({
          email: "ada@example.com",
          password: "correct-horse-battery-staple",
          name: "Ada Lovelace",
        });

        if (!result.error) {
          await checkSession();
        }
      }}
    >
      Create account
    </button>
  );
}

Calling protected routes

For your own protected endpoints, include credentials and the anti-CSRF header. The lower-level SDK request helper is internal, so use fetch directly for app-specific routes.

const response = await fetch("http://localhost:8080/api/me", {
  credentials: "include",
  headers: {
    "X-Authingo-Client": "true",
  },
});

Types

The package exports User, AuthResponse, and AuthError.

import type { AuthError, AuthResponse, User } from "@authingo/react";

React SDK

On this page