Skip to main content
Server TypeScript types used in logto-authkit server-side authentication and middleware.

​
Authentication Types

​
AuthPayload

JWT payload structure returned after token verification.
​
sub
string
required
Subject - the user ID from Logto
​
scope
string
required
OAuth scopes granted to the token
​
[key: string]
any
Additional claims from the JWT token
export interface AuthPayload {
  sub: string // user ID
  scope: string
  [key: string]: any
}

​
AuthContext

Authentication context attached to requests after verification.
​
userId
string | null
required
The authenticated user ID, or null if not authenticated
​
isAuthenticated
boolean
required
Whether the request has a valid authentication token
​
payload
AuthPayload | null
required
The full JWT payload if authenticated, otherwise null
​
isGuest
boolean
Whether the request is from a guest user (when allowGuest is enabled)
​
guestId
string
The guest user ID (when in guest mode)
export interface AuthContext {
  userId: string | null
  isAuthenticated: boolean
  payload: AuthPayload | null
  isGuest?: boolean
  guestId?: string
}

​
VerifyAuthOptions

Configuration options for token verification.
​
logtoUrl
string
required
The Logto tenant URL (e.g., https://your-tenant.logto.app)
​
audience
string
required
The API resource identifier configured in Logto
​
cookieName
string
default:"logto_authtoken"
Name of the cookie containing the JWT token
​
requiredScope
string
Required OAuth scope for authorization (e.g., "read:users")
​
allowGuest
boolean
default:false
Allow unauthenticated guest users with guest IDs
export interface VerifyAuthOptions {
  logtoUrl: string
  audience: string
  cookieName?: string
  requiredScope?: string
  allowGuest?: boolean
}

​
Express Types

​
ExpressRequest

Extended Express request interface with authentication context.
​
cookies
{ [key: string]: string }
Parsed cookies from the request
​
headers
{ [key: string]: string | string[] | undefined }
required
HTTP headers from the request
​
auth
AuthContext
Authentication context added by the middleware
export interface ExpressRequest {
  cookies?: { [key: string]: string }
  headers: { [key: string]: string | string[] | undefined }
  auth?: AuthContext
}

​
ExpressResponse

Express response interface for middleware.
​
status
(code: number) => ExpressResponse
required
Set HTTP status code
​
json
(obj: any) => ExpressResponse
required
Send JSON response
export interface ExpressResponse {
  status: (code: number) => ExpressResponse
  json: (obj: any) => ExpressResponse
}

​
ExpressNext

Express next function type. 
export type ExpressNext = (err?: any) => void

​
Next.js Types

​
NextRequest

Next.js request interface for route handlers and middleware.
​
cookies
{ get: (name: string) => { value: string } | undefined }
required
Cookie accessor for Next.js requests
​
headers
{ get: (name: string) => string | null }
required
Header accessor for Next.js requests
export interface NextRequest {
  cookies: {
    get: (name: string) => { value: string } | undefined
  }
  headers: {
    get: (name: string) => string | null
  }
}

​
NextResponse

Next.js response interface for route handlers.
​
json
(body: any, init?: { status?: number }) => NextResponse
required
Send JSON response with optional status code
export interface NextResponse {
  json: (body: any, init?: { status?: number }) => NextResponse
}

​
Usage Examples

​
Express Middleware

import type { ExpressRequest, ExpressResponse } from '@ouim/logto-authkit/server'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: 'https://your-tenant.logto.app',
  audience: 'https://api.example.com',
  requiredScope: 'read:users'
})

app.get('/api/protected', authMiddleware, (req: ExpressRequest, res: ExpressResponse) => {
  const userId = req.auth?.userId
  res.json({ userId, message: 'Protected data' })
})

​
Next.js Route Handler

import type { NextRequest } from '@ouim/logto-authkit/server'
import { verifyNextAuth } from '@ouim/logto-authkit/server'
import { NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_AUDIENCE!,
  })
  
  if (!result.success || !result.auth.isAuthenticated) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
  
  return NextResponse.json({ userId: result.auth.userId })
}

​
Guest Mode

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

const guestMiddleware = createExpressAuthMiddleware({
  logtoUrl: 'https://your-tenant.logto.app',
  audience: 'https://api.example.com',
  allowGuest: true
})

app.get('/api/content', guestMiddleware, (req, res) => {
  if (req.auth?.isGuest) {
    // Handle guest user
    console.log('Guest ID:', req.auth.guestId)
  } else {
    // Handle authenticated user
    console.log('User ID:', req.auth?.userId)
  }
  
  res.json({ message: 'Content accessible to all' })
})