Access token claims

A Connect access token is a JWT that authorizes an application to call your API or MCP server. Use its claims to identify the caller, check the client’s scopes, and resolve user permissions when access depends on the user’s role.

For tokens that authenticate users in your own application, see Session tokens.

Connect issues user tokens to OAuth applications and MCP clients, including those registered through Dynamic Client Registration (DCR) or Client ID Metadata Document (CIMD). User tokens are issued through the authorization code, refresh token, and device code grants. M2M applications use the client credentials grant to obtain tokens without a user.

The issuer is the HTTPS URL of your AuthKit domain. For user tokens, the audience is the requested resource indicator, or the environment client ID when no resource is configured. The M2M audience is not configurable per application. Granted scopes are a space-delimited string.

User tokens can include additional claims from your environment’s JWT template. M2M tokens do not support JWT templates or custom claims.

Check the client’s scopes to determine what the calling application is allowed to do. Scopes do not enforce the user’s role-based permissions, so a scoped request also needs a user-permission check when access varies by user.

Connect tokens do not include a permissions claim. For user-specific authorization, choose one of these approaches:

• Add roles with a JWT template if your server maintains the role-to-permission mapping.
• Check permissions server-side if WorkOS maintains the mapping. Use this approach if you are unsure which to choose.

For an OAuth application created in the WorkOS dashboard, assign permissions from your environment to the application as scopes. Requesting an unassigned scope fails at the authorization endpoint with invalid_scope; assign that scope or remove it from the request.

Clients registered through Dynamic Client Registration or Client ID Metadata Document cannot have scopes assigned per client. Updating their scopes returns HTTP 422 with Cannot update scopes for dynamically registered applications. These clients receive the standard OpenID Connect scopes: openid, profile, email, and offline_access.

For additional permission scopes on dynamically registered clients, contact support about an environment-wide default set. These scopes still do not restrict access based on the user’s role.

Add organization_membership.roles to your environment’s JWT template to put the user’s role slugs on every Connect user token:

{
  "roles": {{ organization_membership.roles }}
}

{
  "roles": ["admin", "billing"]
}

Permissions are not in the template context. A template that references organization_membership.permissions fails validation with Invalid path. One template applies to the whole environment, so these claims also land on your AuthKit session tokens, which are limited to 3072 bytes of rendered template output.

After verifying the token, use sub and org_id to resolve the user’s effective permissions from the WorkOS API, then gate the request on the result. Cache the result per user and organization so each request doesn’t call the API; a role change is reflected when the cache entry expires.

1. Verify the JWT against https://authkit_domain/oauth2/jwks and check iss and aud.
2. Call List organization memberships with user_id set to sub and organization_id set to org_id. The membership carries role.slug, and roles[] when multiple roles are enabled.
3. For each role slug, call Get a custom role with org_id and the slug. It returns the role’s permissions for both environment roles and organization custom roles.
4. Take the union of the permission slugs and reject the request with 403 if the required permission is missing.

import { jwtVerify, createRemoteJWKSet } from 'jose';
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const JWKS = createRemoteJWKSet(new URL('https://authkit_domain/oauth2/jwks'));

// Permissions are cached per user and organization so each request
// doesn't call the WorkOS API. Role changes apply after the entry expires.
const permissionCache = new Map();
const CACHE_TTL_MS = 60_000;

async function permissionsFor(userId, organizationId) {
  const key = `${userId}:${organizationId}`;
  const cached = permissionCache.get(key);
  if (cached && cached.expiresAt > Date.now()) {
    return cached.permissions;
  }

  const { data: memberships } =
    await workos.userManagement.listOrganizationMemberships({
      userId,
      organizationId,
    });

  const membership = memberships[0];
  if (!membership) {
    return new Set();
  }

  // `roles` is populated when multiple roles are enabled; `role` otherwise.
  const roleSlugs = membership.roles?.map((role) => role.slug) ?? [
    membership.role.slug,
  ];

  const roles = await Promise.all(
    roleSlugs.map((slug) =>
      workos.authorization.getOrganizationRole(organizationId, slug),
    ),
  );

  const permissions = new Set(roles.flatMap((role) => role.permissions));
  permissionCache.set(key, {
    permissions,
    expiresAt: Date.now() + CACHE_TTL_MS,
  });

  return permissions;
}

const requirePermission = (permission) => async (req, res, next) => {
  const token = req.headers.authorization?.match(/^Bearer (.+)$/)?.[1];

  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }

  let payload;
  try {
    ({ payload } = await jwtVerify(token, JWKS, {
      issuer: 'https://authkit_domain',
      audience: 'https://mcp.example.com',
    }));
  } catch (err) {
    return res.status(401).json({ error: 'Invalid token' });
  }

  // Connect tokens carry no `permissions` claim. Resolve them from
  // the user's organization membership instead.
  if (!payload.org_id) {
    return res.status(403).json({ error: 'No organization selected' });
  }

  const permissions = await permissionsFor(payload.sub, payload.org_id);

  if (!permissions.has(permission)) {
    return res.status(403).json({ error: `Missing permission: ${permission}` });
  }

  req.userId = payload.sub;
  req.organizationId = payload.org_id;
  next();
};

// Example protected MCP endpoint
app.post('/mcp', requirePermission('documents:read'), (req, res) => {
  res.json({ data: 'Protected resource', userId: req.userId });
});

A token without org_id belongs to a user who has no organization membership, so there are no roles to resolve. Reject it, or treat it as having no permissions.

To map the calling organization to an identifier in your system, read org_id from the token and call Get an organization once to read external_id or metadata, then persist the mapping. Refresh the cached mapping when the organization’s identifiers change.