Clerk session tokens

Clerk signs users in to your application and gives each session a short-lived JWT. @mayurajs/auth-clerk turns those session tokens into identities for Mayura's server: it is a jwtAuthenticator already set up for your Clerk instance, and your identity mapping decides what each user may do. It verifies tokens with mayura/auth's own JWT verifier (WebCrypto only): no Clerk SDK, no dependency, and it runs on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/auth-clerk

#Credentials

Nothing secret is needed. Copy your instance's publishable key (pk_live_... or pk_test_...) from the API keys page of the Clerk dashboard; your Frontend API URL, which issues the tokens and publishes their keys, is read from it. To verify with no network at all, also copy the JWKS public key (PEM) from the same page and pass it as jwtKey.

The package reads nothing from the environment: pass the values in yourself, for example from CLERK_PUBLISHABLE_KEY and CLERK_AUTHORIZED_PARTY.

#Use it

import { mapCapabilities, principalId } from 'mayura/auth';
import { clerkAuthenticator } from '@mayurajs/auth-clerk';

export const authenticate = clerkAuthenticator({
  publishableKey: process.env.CLERK_PUBLISHABLE_KEY ?? '',
  authorizedParties: ['https://app.example.com'], // the origins your users sign in from
  identity: session => session.orgId ? {
    principalId: principalId('clerk', session.userId),
    projectId: session.orgId,
    agentIds: ['support'],
    capabilities: mapCapabilities(session.orgPermissions, {
      'org:agents:use': ['runs:submit', 'runs:read'],
      'org:agents:operate': ['workflows:read', 'workflows:control'],
    }),
  } : null,
});
// createAgentServer({ ..., authenticate })

Your frontend sends the session token as the bearer token, for example await window.Clerk.session.getToken(). A user outside an organization gets nothing here, and a permission missing from the table grants nothing. See Authentication and API keys for chaining this with API keys and other providers.

#Options

#What is checked

• Signature and issuer. RS256 only, issued by your Frontend API, signed by a key from <frontendApi>/.well-known/jwks.json (or by jwtKey). Keys of any other kind in the set are never used.
• Times. The token must carry exp and be unexpired, with clockSkewMs of leeway.
• Authorized party. Clerk tokens carry no audience. The origin a token was made for (azp) stands in for it, as Clerk advises against CSRF: a token without azp, or for another origin, is refused.
• Session. A token needs sub and sid. Sessions with status pending are refused unless allowPending.

Fetched keys are kept for the JWKS response's max-age, at most 10 minutes; a token with an unknown key id refetches them at most every 30 s. See Tokens from an identity provider for the cache, timeouts and size limits.

#What identity receives

Version 2 tokens carry permissions as feature bitmasks (fea, o.per, o.fpm); the package decodes them as Clerk's SDK does, reading only organization features, and a malformed feature list grants nothing. Version 1 tokens (org_id, org_role, org_permissions) are read too. clerkPermissions(claims), clerkSession(claims) and clerkFrontendApi(publishableKey) are exported for checks of your own.

#Errors

#How it is tested

• Unit tests sign real RS256 tokens with testIssuer from mayura/auth/testing and serve its JWKS through a fake fetch. They check that the Frontend API is read from publishable keys, that tokens for other origins, other instances, other keys, ES256, pending sessions and tokens without sid are refused, that keys are fetched once, that the PEM key verifies with no network, and that version 2 permission bitmasks decode as Clerk documents them.
• scripts/live/auth-clerk.mjs fetched and checked Clerk's published signing keys for a real instance on October 6,
  2026. A real session 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.
• WorkOS AuthKit and Connect tokens and Auth0 access tokens: other hosted sign-in.