Guest Mode

Guest mode allows your application to work with both authenticated and unauthenticated users, providing a seamless experience with built-in fingerprint-based guest IDs.

Overview

When guest mode is enabled:

Unauthenticated users automatically get a unique guest ID
Guest IDs are stored in the guest_logto_authtoken cookie for persistence
Your app can track guest users across sessions
Guest users can later sign in without losing their data

Frontend Setup

Use the useAuth hook with the guest middleware:

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

function MixedContent() {
  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>
  )
}

Middleware Options

The useAuth hook supports different middleware modes:

middleware

'auth' | 'guest'

'auth': Require authentication (redirect if not logged in)
'guest': Allow both authenticated and guest users

redirectTo

string

URL to redirect to when authentication is required (used with middleware: 'auth')

Route Protection with Auth Middleware

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

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

Server Setup

Enable guest mode in your server authentication middleware:

Express.js

import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: 'https://your-logto-domain.com',
  audience: 'your-api-resource-identifier',
  cookieName: 'logto_authtoken',
  allowGuest: true, // Enable guest mode
})

app.get('/api/content', authMiddleware, (req, res) => {
  res.json({
    userId: req.auth.userId,
    isAuthenticated: req.auth.isAuthenticated,
    isGuest: req.auth.isGuest,
    guestId: req.auth.guestId, // Available when isGuest is true
  })
})

Next.js API Routes

import { verifyNextAuth } from '@ouim/logto-authkit/server'

export async function GET(request) {
  const authResult = await verifyNextAuth(request, {
    logtoUrl: 'https://your-logto-domain.com',
    audience: 'your-api-resource-identifier',
    allowGuest: true, // Enable guest mode
  })

  if (!authResult.success) {
    return Response.json({ error: authResult.error }, { status: 401 })
  }

  return Response.json({
    userId: authResult.auth.userId,
    isAuthenticated: authResult.auth.isAuthenticated,
    isGuest: authResult.auth.isGuest,
    guestId: authResult.auth.guestId,
  })
}

Auth Context Structure

When guest mode is enabled, the auth context includes additional fields:

interface AuthContext {
  userId: string | null        // User ID from token (null for guests)
  isAuthenticated: boolean     // true for authenticated users
  isGuest: boolean            // true for guest users
  payload: AuthPayload | null // Full JWT payload (null for guests)
  guestId?: string            // Guest fingerprint ID (when allowGuest is true)
}

How Guest IDs Work

Guest ID Generation

When a user visits your site without authentication, logto-authkit automatically generates a unique guest ID using browser fingerprinting.

Persistence

The guest ID is stored in the browser’s guest_logto_authtoken cookie, ensuring the same ID is used across sessions.

Server Verification

When allowGuest: true is set, the server helpers can return a guest auth context when no valid JWT token is available, using the guest cookie to persist the guest ID.

Upgrade to Authenticated

When a guest user signs in, they receive a proper JWT token. You can associate their previous guest activity with their authenticated account using the guest ID.

Use Cases

Shopping Cart

Allow users to add items to cart before signing in, then associate the cart with their account after login.

Content Personalization

Track guest preferences and browsing history, then merge with their profile when they sign in.

Analytics

Track user behavior for both authenticated and guest users with a consistent identifier.

Gradual Onboarding

Let users explore your app as guests, then prompt them to sign in when they need advanced features.

Example: Tracking Guest to User Conversion

import { useAuth } from '@ouim/logto-authkit'
import { useEffect, useState } from 'react'

function ProductPage() {
  const { user, isLoadingUser } = useAuth({ middleware: 'guest' })
  const [guestId, setGuestId] = useState<string | null>(null)

  useEffect(() => {
    // Store guest ID before user signs in
    if (!user && typeof window !== 'undefined') {
      const storedGuestId = document.cookie
        .split('; ')
        .find((entry) => entry.startsWith('guest_logto_authtoken='))
        ?.split('=')[1] ?? null
      setGuestId(storedGuestId)
    }
  }, [user])

  useEffect(() => {
    // User just signed in - migrate guest data
    if (user && guestId) {
      migrateGuestData(guestId, user.id)
      setGuestId(null)
    }
  }, [user, guestId])

  async function migrateGuestData(guestId: string, userId: string) {
    // Call your API to associate guest data with the user
    await fetch('/api/migrate-guest-data', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ guestId, userId }),
    })
  }

  if (isLoadingUser) return <div>Loading...</div>

  return (
    <div>
      {user ? (
        <p>Welcome back, {user.name}!</p>
      ) : (
        <p>Browsing as guest (ID: {guestId})</p>
      )}
    </div>
  )
}

Guest IDs are stored in a browser cookie and can still be cleared by the user. Don’t rely on them for critical functionality or security. They’re best used for convenience features like cart persistence.

Configuration Options

allowGuest

boolean

default:"false"

Enable guest mode in server middleware

Custom cookie name for both JWT tokens and guest IDs

Next Steps

Server Authentication

Learn more about server authentication

useAuth Hook

Explore all useAuth hook options

Get Started

Frontend

Server

Configuration

Examples

API Reference

Overview

Frontend Setup

Middleware Options

Route Protection with Auth Middleware

Server Setup

Express.js

Next.js API Routes

Auth Context Structure

How Guest IDs Work

Use Cases

Shopping Cart

Content Personalization

Analytics

Gradual Onboarding

Example: Tracking Guest to User Conversion

Configuration Options

Next Steps

Server Authentication

useAuth Hook

​Overview

​Frontend Setup

​Middleware Options

​Route Protection with Auth Middleware

​Server Setup

​Express.js

​Next.js API Routes

​Auth Context Structure

​How Guest IDs Work

​Use Cases

Shopping Cart

Content Personalization

Analytics

Gradual Onboarding

​Example: Tracking Guest to User Conversion

​Configuration Options

​Next Steps

Server Authentication

useAuth Hook

Overview

Frontend Setup

Middleware Options

Route Protection with Auth Middleware

Server Setup

Express.js

Next.js API Routes

Auth Context Structure

How Guest IDs Work

Use Cases

Example: Tracking Guest to User Conversion

Configuration Options

Next Steps