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 once in a shared client module, then import that client from your forms and other client components.

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 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

The exported useSession() 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.

Create a small client-side function for your login flow, then call it from your form onSubmit handler or button click handler after reading the email and password values.

lib/use-sign-in.ts

"use client";

import { authClient } from "@/lib/auth-client";
import { useAuth } from "@authingo/react";

type SignInInput = {
  email: string;
  password: string;
};

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

  return async function signInWithEmail(input: SignInInput) {
    const result = await authClient.signIn.email(input);

    if (!result.error) {
      await checkSession();
    }

    return result;
  };
}

Use useSignInWithEmail() inside a client component rendered under AuthProvider. Call the returned signInWithEmail function from your login form's submit handler.

Use the same pattern for account creation, then refresh the provider session after a successful sign up.

lib/use-sign-up.ts

"use client";

import { authClient } from "@/lib/auth-client";
import { useAuth } from "@authingo/react";

type SignUpInput = {
  email: string;
  password: string;
  name: string;
};

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

  return async function signUpWithEmail(input: SignUpInput) {
    const result = await authClient.signUp.email(input);

    if (!result.error) {
      await checkSession();
    }

    return result;
  };
}

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