Skip to main content

​
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

1

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

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' }
  ]}
/>
3

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 />}
/>
4

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.

​
Next steps

Server authentication

Secure your API endpoints with JWT verification

Bundler configuration

Configure Vite, Webpack, or Next.js bundlers