Skip to main content

​
Overview

The verifyAuth function is a generic authentication verification utility that works in any Node.js environment. It can accept either a raw JWT token string or a request object with cookies and headers.

​
Signature

async function verifyAuth(
  tokenOrRequest: string | { cookies?: any; headers?: any },
  options: VerifyAuthOptions
): Promise<AuthContext>

​
Parameters

​
tokenOrRequest
string | object
required
Either a JWT token string or a request object containing cookies and headersWhen passing an object:
  • cookies: Cookie object (e.g., from cookie-parser)
  • headers: Headers object or Headers API
​
options
VerifyAuthOptions
required
Configuration options for token verification

​
Returns

​
AuthContext
Promise<AuthContext>
Promise that resolves to authentication context

​
Throws

  • Throws an error if no token is found and allowGuest is false
  • Throws an error if token verification fails and allowGuest is false
  • When allowGuest: true, returns guest context instead of throwing

​
Examples

​
With JWT Token String

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

const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

try {
  const auth = await verifyAuth(token, {
    logtoUrl: 'https://your-logto.app',
    audience: 'https://api.yourapp.com'
  })

  console.log('User ID:', auth.userId)
  console.log('Authenticated:', auth.isAuthenticated)
} catch (error) {
  console.error('Authentication failed:', error)
}

​
With Request Object (Generic)

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

const request = {
  cookies: { logto_authtoken: 'eyJhbGciOiJ...' },
  headers: { authorization: 'Bearer eyJhbGciOiJ...' }
}

const auth = await verifyAuth(request, {
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

if (auth.isAuthenticated) {
  console.log('User:', auth.userId)
  console.log('Scopes:', auth.payload?.scope)
}

​
With Guest Support

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

const auth = await verifyAuth(request, {
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  allowGuest: true // Won't throw if no token found
})

if (auth.isGuest) {
  console.log('Guest user:', auth.guestId)
} else {
  console.log('Authenticated user:', auth.userId)
}

​
With Required Scope

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

try {
  const auth = await verifyAuth(token, {
    logtoUrl: process.env.LOGTO_URL,
    audience: process.env.LOGTO_AUDIENCE,
    requiredScope: 'admin:write' // Requires this scope
  })

  // Token has admin:write scope
  console.log('Admin user:', auth.userId)
} catch (error) {
  console.error('Missing required scope')
}

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

const auth = await verifyAuth(request, {
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  cookieName: 'my_custom_auth_cookie'
})

​
Token Extraction Order

When a request object is provided, tokens are extracted in this order:
  1. Cookie (using cookieName option, defaults to logto_authtoken)
  2. Authorization header (Bearer token)
The first valid token found is used for verification.

​
Verification Process

The function performs the following verification steps:
  1. Fetches JWKS (JSON Web Key Set) from your Logto server
  2. Decodes JWT header to identify the signing key
  3. Verifies JWT signature using the public key
  4. Validates token claims:
    • Issuer (iss) matches Logto URL
    • Audience (aud) matches provided audience
    • Token is not expired (exp)
    • Token is valid (nbf - not before)
    • Required scope is present (if specified)

​
Caching

JWKS (signing keys) are cached for 5 minutes to reduce requests to the Logto server and improve performance.

​
See Also