Skip to main content

How to validate access tokens in your API service or backend

Validating access tokens is a critical part of enforcing role-based access control (RBAC) in Logto. This guide walks you through verifying Logto-issued JWTs in your backend/API, checking for signature, issuer, audience, expiration, permissions (scopes), and organization context.

Before you start​

Step 1: Initialize constants and utilities​

Define necessary constants and utilities in your code to handle token extraction and validation. A valid request must include an Authorization header in the form Bearer <access_token>.

auth-middleware.ts
import { IncomingHttpHeaders } from 'http';

const JWKS_URI = 'https://your-tenant.logto.app/oidc/jwks';
const ISSUER = 'https://your-tenant.logto.app/oidc';

export class AuthInfo {
  constructor(
    public sub: string,
    public clientId?: string,
    public organizationId?: string,
    public scopes: string[] = [],
    public audience: string[] = []
  ) {}
}

export class AuthorizationError extends Error {
  name = 'AuthorizationError';
  constructor(
    message: string,
    public status = 403
  ) {
    super(message);
  }
}

export function extractBearerTokenFromHeaders({ authorization }: IncomingHttpHeaders): string {
  const bearerPrefix = 'Bearer ';

  if (!authorization) {
    throw new AuthorizationError('Authorization header is missing', 401);
  }

  if (!authorization.startsWith(bearerPrefix)) {
    throw new AuthorizationError(`Authorization header must start with "${bearerPrefix}"`, 401);
  }

  return authorization.slice(bearerPrefix.length);
}

Step 2: Retrieve info about your Logto tenant​

You’ll need the following values to validate Logto-issued tokens:

  • JSON Web Key Set (JWKS) URI: The URL to Logto’s public keys, used to verify JWT signatures.
  • Issuer: The expected issuer value (Logto’s OIDC URL).

First, find your Logto tenant’s endpoint. You can find it in various places:

  • In the Logto Console, under Settings → Domains.
  • In any application settings where you configured in Logto, Settings → Endpoints & Credentials.

Fetch from OpenID Connect discovery endpoint​

These values can be retrieved from Logto’s OpenID Connect discovery endpoint:

https://<your-logto-endpoint>/oidc/.well-known/openid-configuration

Here’s an example response (other fields omitted for brevity):

{
  "jwks_uri": "https://your-tenant.logto.app/oidc/jwks",
  "issuer": "https://your-tenant.logto.app/oidc"
}

Since Logto doesn't allow customizing the JWKS URI or issuer, you can hardcode these values in your code. However, this is not recommended for production applications as it may increase maintenance overhead if some configuration changes in the future.

  • JWKS URI: https://<your-logto-endpoint>/oidc/jwks
  • Issuer: https://<your-logto-endpoint>/oidc

Step 3: Validate the token and permissions​

After extracting the token and fetching the OIDC config, validate the following:

  • Signature: JWT must be valid and signed by Logto (via JWKS).
  • Issuer: Must match your Logto tenant’s issuer.
  • Audience: Must match the API’s resource indicator registered in Logto, or the organization context if applicable.
  • Expiration: Token must not be expired.
  • Permissions (scopes): Token must include required scopes for your API/action. Scopes are space-separated strings in the scope claim.
  • Organization context: If protecting organization-level API resources, validate the organization_id claim.

See JSON Web Token to learn more about JWT structure and claims.

What to check for each permission model​

The claims and validation rules differ by permission model:

  • Audience claim (aud): API resource indicator
  • Organization claim (organization_id): Not present
  • Scopes (permissions) to check (scope): API resource permissions

For non-API organization permissions, the organization context is represented by the aud claim (e.g., urn:logto:organization:abc123). The organization_id claim is only present for organization-level API resource tokens.
tip:

Always validate both permissions (scopes) and context (audience, organization) for secure multi-tenant APIs.

Add the validation logic​

We use jose in this example to validate the JWT. Install it if you haven't already:

npm install jose

Or use your preferred package manager (e.g., pnpm or yarn).

First, add these shared utilities to handle JWT validation:

jwt-validator.ts
import { createRemoteJWKSet, jwtVerify, JWTPayload } from 'jose';
import { AuthInfo, AuthorizationError } from './auth-middleware.js';

const jwks = createRemoteJWKSet(new URL(JWKS_URI));

export async function validateJwt(token: string): Promise<JWTPayload> {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
  });

  verifyPayload(payload);
  return payload;
}

export function createAuthInfo(payload: JWTPayload): AuthInfo {
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  const audience = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];

  return new AuthInfo(
    payload.sub!,
    payload.client_id as string,
    payload.organization_id as string,
    scopes,
    audience
  );
}

function verifyPayload(payload: JWTPayload): void {
  // Implement your verification logic here based on permission model
  // This will be shown in the permission models section below
}

Then, implement the middleware to verify the access token:

auth-middleware.ts
import { Request, Response, NextFunction } from 'express';
import { validateJwt, createAuthInfo } from './jwt-validator.js';

// Extend Express Request interface to include auth
declare global {
  namespace Express {
    interface Request {
      auth?: AuthInfo;
    }
  }
}

export async function verifyAccessToken(req: Request, res: Response, next: NextFunction) {
  try {
    const token = extractBearerTokenFromHeaders(req.headers);
    const payload = await validateJwt(token);

    // Store auth info in request for generic use
    req.auth = createAuthInfo(payload);

    next();
  } catch (err: any) {
    return res.status(err.status ?? 401).json({ error: err.message });
  }
}

According to your permission model, implement the appropriate verification logic in jwt-validator.ts:

jwt-validator.ts
function verifyPayload(payload: JWTPayload): void {
  // Check audience claim matches your API resource indicator
  const audiences = Array.isArray(payload.aud) ? payload.aud : payload.aud ? [payload.aud] : [];
  if (!audiences.includes('https://your-api-resource-indicator')) {
    throw new AuthorizationError('Invalid audience');
  }

  // Check required scopes for global API resources
  const requiredScopes = ['api:read', 'api:write']; // Replace with your actual required scopes
  const scopes = (payload.scope as string)?.split(' ') ?? [];
  if (!requiredScopes.every((scope) => scopes.includes(scope))) {
    throw new AuthorizationError('Insufficient scope');
  }
}

Step 4: Apply middleware to your API​

Apply the middleware your protected API routes.

app.ts
import { verifyAccessToken } from './auth-middleware.js';

app.get('/api/protected', verifyAccessToken, (req, res) => {
  // Access auth information directly from req.auth
  res.json({ auth: req.auth });
});

Step 5: Test your implementation​

Get access tokens​

From your client application: If you've set up a client integration, your app can obtain tokens automatically. Extract the access token and use it in API requests.

For testing with curl/Postman:

  1. User tokens: Use your client app's developer tools to copy the access token from localStorage or the network tab

  2. Machine-to-machine tokens: Use the client credentials flow. Here's a non-normative example using curl:

    curl -X POST https://your-tenant.logto.app/oidc/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=your-m2m-client-id" \
      -d "client_secret=your-m2m-client-secret" \
      -d "resource=https://your-api-resource-indicator" \
      -d "scope=api:read api:write"

    You may need to adjust the resource and scope parameters based on your API resource and permissions; an organization_id parameter may also be required if your API is organization-scoped.

tip:

Need to inspect the token contents? Use our JWT decoder to decode and verify your JWTs.

Test protected endpoints​

Valid token request
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/api/protected

Expected response:

{
  "auth": {
    "sub": "user123",
    "clientId": "app456",
    "organizationId": "org789",
    "scopes": ["api:read", "api:write"],
    "audience": ["https://your-api-resource-indicator"]
  }
}
Missing token
curl http://localhost:3000/api/protected

Expected response (401):

{
  "error": "Authorization header is missing"
}
Invalid token
curl -H "Authorization: Bearer invalid-token" \
  http://localhost:3000/api/protected

Expected response (401):

{
  "error": "Invalid token"
}

Permission model-specific testing​

Test scenarios for APIs protected with global scopes:

  • Valid scopes: Test with tokens that include your required API scopes (e.g., api:read, api:write)
  • Missing scopes: Expect 403 Forbidden when token lacks required scopes
  • Wrong audience: Expect 403 Forbidden when audience does not match the API resource
# Token with missing scopes - expect 403
curl -H "Authorization: Bearer token-without-required-scopes" \
  http://localhost:3000/api/protected
Customizing token claims JSON Web Token (JWT)

OpenID Connect Discovery

 RFC 8707: Resource Indicators