createExpressAuthMiddleware

Overview

The createExpressAuthMiddleware function creates an Express middleware that automatically verifies Logto authentication tokens and attaches authentication context to the request object.

Signature

function createExpressAuthMiddleware(
  options: VerifyAuthOptions
): (req: ExpressRequest, res: ExpressResponse, next: ExpressNext) => void

Parameters

options

VerifyAuthOptions

required

Configuration options for token verification

Show VerifyAuthOptions properties

logtoUrl

string

required

Your Logto server URL (e.g., https://your-logto.app)

audience

string

required

Expected audience claim in the token (your application identifier)

Name of the cookie containing the auth token

requiredScope

string

Required OAuth scope that must be present in the token

allowGuest

boolean

default:false

Allow guest access when no valid token is found. Attaches guest context instead of returning 401

Returns

middleware

ExpressMiddleware

Express middleware function that can be used with app.use() or route handlers

Request Enhancement

The middleware adds an auth property to the Express request object:

req.auth: AuthContext

Show AuthContext properties

userId

string | null

User ID from the token’s sub claim, or null for guest users

isAuthenticated

boolean

Whether the user is authenticated (true) or guest (false)

payload

AuthPayload | null

Decoded JWT payload, or null for guest users

isGuest

boolean

true if this is a guest context (only when allowGuest: true)

guestId

string

Unique identifier for guest users (auto-generated UUID)

Examples

Basic Setup

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

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

// Apply to all routes
app.use(authMiddleware)

app.get('/profile', (req, res) => {
  res.json({
    userId: req.auth.userId,
    authenticated: req.auth.isAuthenticated
  })
})

app.listen(3000)

Protected Routes Only

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

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

// Public route (no auth required)
app.get('/public', (req, res) => {
  res.json({ message: 'Public endpoint' })
})

// Protected routes
app.get('/api/user', authMiddleware, (req, res) => {
  res.json({ userId: req.auth.userId })
})

app.post('/api/data', authMiddleware, (req, res) => {
  const userId = req.auth.userId
  // Handle authenticated request
  res.json({ success: true })
})

With Guest Support

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

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  allowGuest: true // Allow unauthenticated access
})

app.use(authMiddleware)

app.get('/api/content', (req, res) => {
  if (req.auth.isGuest) {
    res.json({
      message: 'Limited content for guests',
      guestId: req.auth.guestId
    })
  } else {
    res.json({
      message: 'Full content for authenticated users',
      userId: req.auth.userId
    })
  }
})

With Required Scope

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

const app = express()

const adminAuthMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  requiredScope: 'admin:write'
})

// Admin-only endpoint
app.delete('/api/users/:id', adminAuthMiddleware, (req, res) => {
  // Only users with admin:write scope can access this
  res.json({ success: true })
})

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

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  cookieName: 'my_custom_auth_cookie'
})

app.use(authMiddleware)

Error Handling

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

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

app.use(authMiddleware)

// Authentication errors return 401 automatically
// Add error handler for custom error responses
app.use((err, req, res, next) => {
  if (err.status === 401) {
    res.status(401).json({
      error: 'Unauthorized',
      message: 'Please sign in to access this resource'
    })
  } else {
    next(err)
  }
})

Behavior

Token Extraction

The middleware extracts tokens in this order:

Cookie (using cookieName option, defaults to logto_authtoken)
Authorization header (Bearer token)

Authentication Responses

When allowGuest: false (default):

No token found: Returns 401 with error message
Invalid token: Returns 401 with error details
Valid token: Attaches AuthContext to req.auth and calls next()

When allowGuest: true:

No token found: Attaches guest AuthContext to req.auth and calls next()
Invalid token: Attaches guest AuthContext to req.auth and calls next()
Valid token: Attaches authenticated AuthContext to req.auth and calls next()

The middleware automatically handles cookie parsing:

If cookies are not already parsed, it applies cookie-parser internally
No need to manually add cookie-parser middleware when using this middleware

TypeScript Support

Extend the Express request type to include the auth property:

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

declare global {
  namespace Express {
    interface Request {
      auth: AuthContext
    }
  }
}

Get Started

Frontend

Server

Configuration

Examples

API Reference

createExpressAuthMiddleware

Overview

Signature

Parameters

Returns

Request Enhancement

Examples

Basic Setup

Protected Routes Only

With Guest Support

With Required Scope

Error Handling

Behavior

Token Extraction

Authentication Responses

TypeScript Support

See Also

​Overview

​Signature

​Parameters

​Returns

​Request Enhancement

​Examples

​Basic Setup

​Protected Routes Only

​With Guest Support

​With Required Scope

​Custom Cookie Name

​Error Handling

​Behavior

​Token Extraction

​Authentication Responses

​Cookie Parsing

​TypeScript Support

​See Also

Overview

Signature

Parameters

Returns

Request Enhancement

Examples

Basic Setup

Protected Routes Only

With Guest Support

With Required Scope

Custom Cookie Name

Error Handling

Behavior

Token Extraction

Authentication Responses

Cookie Parsing

TypeScript Support

See Also