Server Types

Server TypeScript types used in logto-authkit server-side authentication and middleware.

Authentication Types

AuthPayload

JWT payload structure returned after token verification.

string

required

Subject - the user ID from Logto

string

required

OAuth scopes granted to the token

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.

string | null

required

The authenticated user ID, or null if not authenticated

boolean

required

Whether the request has a valid authentication token

AuthPayload | null

required

The full JWT payload if authenticated, otherwise null

boolean

Whether the request is from a guest user (when allowGuest is enabled)

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.

string

required

The Logto tenant URL (e.g., https://your-tenant.logto.app)

string

required

The API resource identifier configured in Logto

Name of the cookie containing the JWT token

string

Required OAuth scope for authorization (e.g., "read:users")

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.

{ [key: string]: string }

Parsed cookies from the request

{ [key: string]: string | string[] | undefined }

required

HTTP headers from the request

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.

(code: number) => ExpressResponse

required

Set HTTP status code

(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.

{ get: (name: string) => { value: string } | undefined }

required

Cookie accessor for Next.js requests

{ 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.

(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' })
})

Get Started

Frontend

Server

Configuration

Examples

API Reference

Authentication Types

AuthPayload

AuthContext

VerifyAuthOptions

Express Types

ExpressRequest

ExpressResponse

ExpressNext

Next.js Types

NextRequest

NextResponse

Usage Examples

Express Middleware

Next.js Route Handler

Guest Mode