API Gateway

The API Gateway is a managed reverse proxy that sits in front of your API. Requests arrive on a WorkOS-managed gateway domain, or on your own custom domain, where the gateway authenticates the caller – using an API key or an AuthKit session – mints a short-lived, signed identity assertion, and forwards the request to your origin.

Your origin then trusts a single WorkOS-signed assertion instead of re-implementing authentication on every request.

1. A client sends a request to your gateway domain, including its credentials – an API key or an AuthKit session.
2. The gateway authenticates the caller at the edge.
3. The gateway signs a short-lived assertion describing the caller and attaches it as the X-WorkOS-Gateway-Assertion header.
4. The gateway proxies the request to your origin over HTTPS.

The assertion is your origin’s perimeter: it proves the request passed through the gateway and carries the caller’s verified identity. The gateway strips any client-supplied X-WorkOS-Gateway-Assertion header before signing its own, so a caller can’t forge one.

The X-WorkOS-Gateway-Assertion header contains a JSON Web Token (JWT) signed with RS256 using a per-environment key. Each assertion is valid for approximately 60 seconds.

The token includes the standard registered claims:

It also includes WorkOS-specific claims that describe the caller:

The claims present depend on subject_type:

• api_key – sub is the API key id, with org_id, plus user_id and permissions when the key has them.
• authkit_session – sub is the user id, with org_id, roles, and permissions when present.
• anonymous – only subject_type is set. The request reached the gateway without credentials, and your origin decides whether to allow it.

Verify the assertion on every request, and reject any request that doesn’t carry a valid one.

1. Read the X-WorkOS-Gateway-Assertion header.
2. Fetch the per-environment JSON Web Key Set (JWKS) from https://<your-gateway-domain>/.well-known/jwks.json.
3. Verify the token’s signature, along with its iss, aud, and exp.
4. Authorize the request using the verified claims.

import { createRemoteJWKSet, jwtVerify } from 'jose';

// Your gateway domain issues the assertion and serves the per-environment JWKS.
const GATEWAY_URL = 'https://api.example.com';
// The audience configured for your gateway — usually the same as your gateway URL.
const AUDIENCE = GATEWAY_URL;

const jwks = createRemoteJWKSet(
  new URL(`${GATEWAY_URL}/.well-known/jwks.json`),
);

async function verifyGatewayAssertion(request) {
  const token = request.headers['x-workos-gateway-assertion'];
  if (!token) {
    throw new Error('Missing gateway assertion');
  }

  const { payload } = await jwtVerify(token, jwks, {
    issuer: GATEWAY_URL,
    audience: AUDIENCE,
  });

  // payload.subject_type, payload.sub, payload.org_id, payload.permissions, ...
  return payload;
}

Authorize each request from the verified claims. Switch on subject_type to handle API keys, AuthKit sessions, and anonymous traffic, then use sub, org_id, and permissions or roles to make an authorization decision. Because the gateway has already authenticated the caller, your origin only needs to authorize the identity in the assertion.