Quick start

This guide will help you set up logto-authkit authentication in your React application in just a few steps.

Prerequisites

Before you begin, make sure you have:

A Logto account and application configured
Your Logto endpoint URL and app ID
logto-authkit installed in your project

Don’t have a Logto account? Sign up for free and create your first application.

Setup steps

Wrap your app with AuthProvider

Wrap your application with the AuthProvider component and pass your Logto configuration:

src/App.tsx

import { AuthProvider } from '@ouim/logto-authkit'

const config = {
  endpoint: 'https://your-logto-endpoint.com',
  appId: 'your-app-id',
}

function App() {
  return (
    <AuthProvider
      config={config}
      callbackUrl="http://localhost:3000/callback"
    >
      <YourApp />
    </AuthProvider>
  )
}

For single-page applications, pass a customNavigate function to integrate with your router:

<AuthProvider
  config={config}
  callbackUrl="http://localhost:3000/callback"
  customNavigate={(url, options) => {
    // Your navigation logic here
  }}
>

Add the UserCenter component

Drop the UserCenter component into your navbar for a ready-to-use user menu:

src/components/Navbar.tsx

import { UserCenter } from '@ouim/logto-authkit'

function Navbar() {
  return (
    <nav className="flex items-center justify-between h-16 px-4 border-b">
      <div className="font-bold">MyApp</div>
      <UserCenter />
    </nav>
  )
}

The UserCenter component automatically shows:

Avatar, name, and sign out button when authenticated
Sign in button when not authenticated

Customize the UserCenter with additional pages:

<UserCenter
  additionalPages={[
    { link: '/settings', text: 'Settings' },
    { link: '/profile', text: 'Profile' }
  ]}
/>

Create a callback route

Create a route at /callback and render the CallbackPage component to handle OAuth redirects:

src/pages/Callback.tsx

import { CallbackPage } from '@ouim/logto-authkit'

export default function Callback() {
  return <CallbackPage />
}

The CallbackPage handles:

OAuth callback flow
Popup authentication flow
Redirects after successful authentication

Customize the callback experience with optional props:

<CallbackPage
  onSuccess={() => console.log('Auth success!')}
  onError={(error) => console.error('Auth error:', error)}
  loadingComponent={<CustomLoader />}
/>

Use the useAuth hook

Access user data and authentication actions anywhere in your app with the useAuth hook:

src/components/Dashboard.tsx

import { useAuth } from '@ouim/logto-authkit'

function Dashboard() {
  const { user, isLoadingUser, signIn, signOut } = useAuth()

  if (isLoadingUser) return <div>Loading...</div>
  if (!user) return <button onClick={() => signIn()}>Sign in</button>

  return (
    <div>
      <p>Welcome, {user.name}!</p>
      <button onClick={() => signOut()}>Sign out</button>
    </div>
  )
}

Route protection

Protect routes by requiring authentication with the middleware option:

src/pages/ProtectedPage.tsx

import { useAuth } from '@ouim/logto-authkit'

function ProtectedPage() {
  const { user } = useAuth({
    middleware: 'auth',
    redirectTo: '/login', // Redirect if not authenticated
  })

  if (!user) return null // or loading indicator
  
  return <div>Protected content</div>
}

Guest mode

Allow anonymous users to access your app with guest mode:

src/pages/PublicPage.tsx

import { useAuth } from '@ouim/logto-authkit'

function PublicPage() {
  const { user } = useAuth({
    middleware: 'guest', // Allow guest users
  })

  return (
    <div>
      {user ? (
        <p>Welcome back, {user.name}!</p>
      ) : (
        <p>You're browsing as a guest</p>
      )}
    </div>
  )
}

Refresh authentication

Manually refresh the authentication state when needed:

src/components/RefreshButton.tsx

import { useAuth } from '@ouim/logto-authkit'

function RefreshButton() {
  const { refreshAuth } = useAuth()

  return (
    <button onClick={refreshAuth}>
      Refresh Auth
    </button>
  )
}

Enable popup-based sign-in for a better user experience:

src/App.tsx

<AuthProvider
  config={config}
  callbackUrl="http://localhost:3000/callback"
  enablePopupSignIn={true}
>
  <YourApp />
</AuthProvider>

With popup sign-in enabled:

Authentication happens in a popup window
Main page doesn’t reload
Users stay on the same page after signing in

Popup sign-in requires a /signin route. Make sure to create one if using this feature.

Get Started

Frontend

Server

Configuration

Examples

API Reference

Quick start

Quick start

Prerequisites

Setup steps

Route protection

Guest mode

Refresh authentication

Next steps

Server authentication

Bundler configuration

​Quick start

​Prerequisites

​Setup steps

​Route protection

​Guest mode

​Refresh authentication

​Popup sign-in (optional)

​Next steps

Server authentication

Bundler configuration

Quick start

Prerequisites

Setup steps

Route protection

Guest mode

Refresh authentication

Popup sign-in (optional)

Next steps