> ## 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
## Overview
The `AuthProvider` component is the core wrapper for logto-authkit authentication. It manages authentication state, handles sign-in/sign-out operations, and provides auth context to your entire application.
## Installation
The `AuthProvider` is included in the logto-authkit package:
```bash theme={null}
npm install @ouim/logto-authkit
```
## Basic Usage
Wrap your application with `AuthProvider` at the root level:
```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'
function App() {
return (
{/* Your app components */}
)
}
```
## Props
Logto configuration object containing authentication settings.
Your Logto instance endpoint URL
Your Logto application ID
Array of API resource identifiers
The URL to redirect to after authentication. Defaults to current page.
```tsx theme={null}
```
Enable popup-based sign-in instead of full page redirects.
```tsx theme={null}
```
Custom navigation function for framework-specific routing (e.g., Next.js router).
Use replaceState instead of pushState
Force navigation even if already on the same page
```tsx theme={null}
import { useRouter } from 'next/router'
function App() {
const router = useRouter()
return (
{
if (options?.replace) {
router.replace(url)
} else {
router.push(url)
}
}}
>
)
}
```
Your application components that need access to authentication context.
## Features
### Automatic State Management
The `AuthProvider` automatically:
* Fetches and updates user information when authentication state changes
* Handles JWT token storage in cookies
* Syncs authentication across browser tabs and windows
* Refreshes auth state on window focus
* Manages loading states during authentication operations
### Popup Sign-In Support
When `enablePopupSignIn` is enabled, sign-in operations open in a popup window instead of redirecting the entire page:
```tsx theme={null}
{children}
```
Popup sign-in provides a better user experience as it doesn't interrupt the user's current page state.
### Cross-Tab Synchronization
Authentication state is automatically synchronized across browser tabs:
* Sign in on one tab → all tabs update
* Sign out on one tab → all tabs update
* Uses localStorage events and custom event dispatching
### Error Handling
The provider includes robust error handling:
* Automatic logout on invalid/expired tokens
* Rate limiting to prevent excessive API calls
* Graceful fallback for popup authentication failures
## Advanced Usage
### Next.js App Router
```tsx app/layout.tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
### With Custom Navigation (Next.js)
```tsx theme={null}
'use client'
import { AuthProvider } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'
export function AuthProviderWrapper({ children }: { children: React.ReactNode }) {
const router = useRouter()
return (
{
if (options?.replace) {
router.replace(url)
} else {
router.push(url)
}
}}
>
{children}
)
}
```
## Context Value
The `AuthProvider` exposes the following context value (accessible via `useAuth` hook):
```typescript theme={null}
interface AuthContextType {
user: LogtoUser | null
isLoadingUser: boolean
signIn: (callbackUrl?: string, usePopup?: boolean) => Promise
signOut: (options?: { callbackUrl?: string; global?: boolean }) => Promise
refreshAuth: () => Promise
enablePopupSignIn?: boolean
}
```
## Best Practices
Always wrap your entire application with `AuthProvider` to ensure all components have access to authentication context.
Store sensitive configuration like `endpoint` and `appId` in environment variables, not hardcoded in your source.
For better user experience, enable `enablePopupSignIn` to avoid full page redirects during authentication.
The provider includes built-in SSR handling with `ClientOnly` wrapper. No additional configuration needed for Next.js.
## Troubleshooting
If you see "useAuthContext must be used within an AuthProvider" error, ensure the `AuthProvider` wraps your component tree.
The provider automatically handles token refresh and manages authentication state across page navigations.
## Related
Access authentication state and methods
Handle authentication callbacks
Pre-built user menu component
Protect routes and pages