WorkOS AuthKit and Connect tokens

WorkOS AuthKit signs users in to your application, with organizations, roles and enterprise SSO, and Connect issues OAuth access tokens, also to machines. @mayurajs/auth-workos turns AuthKit session tokens, and optionally Connect access tokens, into identities for Mayura's server; your identity mapping decides what each holder may do. It verifies tokens with mayura/auth's own JWT verifier (WebCrypto only): no WorkOS SDK, no dependency, and it runs on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/auth-workos

#Credentials

Nothing secret is needed: only your environment's client ID (client_...), shown in the WorkOS dashboard under API Keys. To accept Connect tokens too, also give your AuthKit domain, such as https://acme.authkit.app, shown on the dashboard's AuthKit settings. The package reads nothing from the environment: pass the values in yourself, for example from WORKOS_CLIENT_ID and WORKOS_AUTHKIT_DOMAIN.

#Use it

import { mapCapabilities, principalId } from 'mayura/auth';
import { workosAuthenticator } from '@mayurajs/auth-workos';

export const authenticate = workosAuthenticator({
  clientId: process.env.WORKOS_CLIENT_ID ?? '',
  connect: { domain: process.env.WORKOS_AUTHKIT_DOMAIN ?? '' }, // optional: Connect tokens too
  identity: session => session.orgId ? {
    principalId: principalId('workos', session.subject),
    projectId: session.orgId,
    agentIds: ['support'],
    capabilities: mapCapabilities(session.kind === 'authkit' ? session.permissions : session.scopes, {
      'agents:use': ['runs:submit', 'runs:read'],
    }),
  } : null,
});
// createAgentServer({ ..., authenticate })

Your frontend sends the AuthKit access token (or a client sends its Connect access token) as the bearer token.

#Options

#What is checked

• AuthKit session tokens. RS256, issued by issuer (with the trailing slash AuthKit writes on https://api.workos.com/), verified only with the keys WorkOS publishes for your client at https://api.workos.com/sso/jwks/<clientId>. They carry no audience.
• Connect tokens (with connect). RS256, issued by your AuthKit domain's origin for audience, verified with the keys at <domain>/oauth2/jwks. A token with no consent (sid) whose subject is its own client_id is a machine's, and is refused unless allowMachines.
• Times and subject. Every token must carry exp and be unexpired, with clockSkewMs of leeway, and have a sub.
• Only the keys of a token's own issuer are fetched, so a token naming another issuer never makes it fetch. When your custom auth domain is also your AuthKit domain, a token is checked as an AuthKit token first, then as a Connect token.

Fetched keys are kept as described in Tokens from an identity provider.

#What identity receives

workosSession(claims, kind) is exported for checks of your own.

#Errors

#How it is tested

• Unit tests sign real RS256 tokens for both kinds and serve both JWKS URLs through a fake fetch. They check that AuthKit tokens read the organization, role and permissions, that other issuers and keys are refused, that Connect tokens are refused unless connect is set, that only the token's own issuer's keys are fetched, that machines need allowMachines, and that a shared custom domain accepts both kinds.
• scripts/live/auth-workos.mjs fetched and checked WorkOS's published signing keys on October 6, 2026. A real token has not been verified with it yet.

#Related

• Authentication and API keys: the verifier, key caching and identity mapping.
• Server and client: capabilities and auth errors.
• Clerk session tokens and Okta access tokens: other hosted sign-in.