> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouim.me/llms.txt
> Use this file to discover all available pages before exploring further.

# AuthProvider

> The main authentication provider component that wraps your application with Logto authentication.

## Overview

The `AuthProvider` component is the root authentication provider that wraps your application and provides authentication context to all child components. It integrates with Logto's authentication service and manages user session state.

## Props

<ParamField path="children" type="React.ReactNode" required>
  The child components to be wrapped by the authentication provider.
</ParamField>

<ParamField path="config" type="LogtoConfig" required>
  Logto configuration object containing your application credentials and settings.

  ```typescript theme={null}
  interface LogtoConfig {
    endpoint: string
    appId: string
    resources?: string[]
    scopes?: string[]
    prompt?: string
  }
  ```
</ParamField>

<ParamField path="callbackUrl" type="string">
  The URL to redirect to after successful authentication. Defaults to the current page URL if not specified.
</ParamField>

<ParamField path="customNavigate" type="(url: string, options?: NavigationOptions) => void">
  Custom navigation function to handle routing in your application. Useful for integration with client-side routers like Next.js or React Router.

  ```typescript theme={null}
  interface NavigationOptions {
    replace?: boolean // Use replaceState instead of pushState
    force?: boolean   // Force navigation even if already on the same page
  }
  ```
</ParamField>

<ParamField path="enablePopupSignIn" type="boolean" default="false">
  Enable popup-based sign-in flow instead of full-page redirect. When enabled, the sign-in page opens in a popup window.
</ParamField>

## Usage

### Basic Setup

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

function App() {
  const logtoConfig = {
    endpoint: 'https://your-logto-endpoint.com',
    appId: 'your-app-id',
  }

  return (
    <AuthProvider config={logtoConfig}>
      <YourApp />
    </AuthProvider>
  )
}
```

### With Callback URL

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

function App() {
  const logtoConfig = {
    endpoint: 'https://your-logto-endpoint.com',
    appId: 'your-app-id',
  }

  return (
    <AuthProvider 
      config={logtoConfig}
      callbackUrl="/dashboard"
    >
      <YourApp />
    </AuthProvider>
  )
}
```

### With Popup Sign-In

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

function App() {
  const logtoConfig = {
    endpoint: 'https://your-logto-endpoint.com',
    appId: 'your-app-id',
  }

  return (
    <AuthProvider 
      config={logtoConfig}
      enablePopupSignIn={true}
    >
      <YourApp />
    </AuthProvider>
  )
}
```

### With Custom Navigation (Next.js)

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'

function App({ children }) {
  const router = useRouter()
  
  const logtoConfig = {
    endpoint: 'https://your-logto-endpoint.com',
    appId: 'your-app-id',
  }

  const customNavigate = (url: string, options?: NavigationOptions) => {
    if (options?.replace) {
      router.replace(url)
    } else {
      router.push(url)
    }
  }

  return (
    <AuthProvider 
      config={logtoConfig}
      customNavigate={customNavigate}
    >
      {children}
    </AuthProvider>
  )
}
```

## Features

* **Client-Side Only**: Automatically prevents SSR issues by rendering only on the client side
* **Cross-Tab Synchronization**: Auth state is synchronized across browser tabs and windows
* **Auto Token Management**: Automatically manages JWT tokens in cookies
* **Error Handling**: Built-in error recovery and automatic logout on auth failures
* **Popup Support**: Optional popup-based authentication flow
* **Rate Limiting**: Prevents excessive auth state refresh calls

## Notes

* The `AuthProvider` must be placed at the root of your component tree, above any components that use authentication
* Configuration is validated on mount to ensure all required fields are present
* Auth state changes trigger a custom `auth-state-changed` event on the window object
* The provider automatically handles token refresh and session management