feat(backend,nextjs): Add support for M2M JWT creation and verification

.changeset/clever-ways-raise.md

@@ -0,0 +1,2 @@
+---
+---

integration/tests/machine-auth/m2m.test.ts

@@ -42,10 +42,9 @@ test.describe('machine-to-machine auth @machine', () => {
 
  app.get('/api/protected', async (req, res) => {
  const token = req.get('Authorization')?.split(' ')[1];
-
  try {
  const m2mToken = await clerkClient.m2m.verify({ token });
- res.send('Protected response ' + m2mToken.id);
+ res.send('Protected response ' + m2mToken.subject);
  } catch {
  res.status(401).send('Unauthorized');
  }
@@ -150,7 +149,7 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res.status()).toBe(200);
- expect(await res.text()).toBe('Protected response ' + emailServerM2MToken.id);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
 
  // Analytics server can access primary API server after adding scope
  await u.services.clerk.machines.createScope(analyticsServer.id, primaryApiServer.id);
@@ -165,9 +164,30 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res2.status()).toBe(200);
- expect(await res2.text()).toBe('Protected response ' + m2mToken.id);
+ expect(await res2.text()).toBe('Protected response ' + analyticsServer.id);
  await u.services.clerk.m2m.revokeToken({
  m2mTokenId: m2mToken.id,
  });
  });
+
+ test('verifies JWT format M2M token via local verification', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+
+ const client = createClerkClient({
+ secretKey: instanceKeys.get('with-api-keys').sk,
+ });
+ const jwtToken = await client.m2m.createToken({
+ machineSecretKey: emailServer.secretKey,
+ secondsUntilExpiration: 60 * 30,
+ tokenFormat: 'jwt',
+ });
+
+ const res = await u.page.request.get(app.serverUrl + '/api/protected', {
+ headers: { Authorization: `Bearer ${jwtToken.token}` },
+ });
+ expect(res.status()).toBe(200);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
+ // JWT-format tokens are self-contained and not stored in BAPI, so revocation
+ // is not applicable — they expire naturally via the exp claim.
+ });
 });

packages/backend/src/__tests__/exports.test.ts

@@ -49,11 +49,9 @@ describe('subpath /internal exports', () => {
  "decorateObjectWithResources",
  "getAuthObjectForAcceptedToken",
  "getAuthObjectFromJwt",
- "getMachineTokenType",
  "invalidTokenAuthObject",
  "isMachineToken",
  "isMachineTokenByPrefix",
- "isMachineTokenType",
  "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -1,8 +1,12 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { mockJwks, mockJwtPayload, mockM2MJwtPayload, signingJwks } from '../../fixtures';
+import { signJwt } from '../../jwt/signJwt';
 import { server, validateHeaders } from '../../mock-server';
+import { M2MTokenApi } from '../endpoints/M2MTokenApi';
 import { createBackendApiClient } from '../factory';
+import { buildRequest } from '../request';
 
 describe('M2MToken', () => {
  const m2mId = 'mt_1xxxxxxxxxxxxx';
@@ -110,6 +114,130 @@ describe('M2MToken', () => {
  'The provided Machine Secret Key is invalid. Make sure that your Machine Secret Key is correct.',
  );
  });
+
+ it('creates a jwt format m2m token', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ return HttpResponse.json({
+ ...mockM2MToken,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJpYXQiOjE3NTM3NDMzMTYsImV4cCI6MTc1Mzc0NjkxNn0.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ });
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates a jwt m2m token with custom claims and scopes', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ const customClaims = {
+ role: 'service',
+ tier: 'gold',
+ };
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ expect(body.claims).toEqual(customClaims);
+ return HttpResponse.json({
+ ...mockM2MToken,
+ claims: customClaims,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJyb2xlIjoic2VydmljZSIsInRpZXIiOiJnb2xkIiwiaWF0IjoxNzUzNzQzMzE2LCJleHAiOjE3NTM3NDY5MTZ9.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ claims: customClaims,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.claims).toEqual(customClaims);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates an opaque format m2m token when explicitly specified', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'opaque',
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ expect(response.token).toMatch(/^mt_.+$/);
+ });
+
+ it('creates an opaque m2m token by default when tokenFormat is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ // tokenFormat defaults to 'opaque' when omitted
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ secondsUntilExpiration: 3600,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ });
  });
 
  describe('revoke', () => {
@@ -283,6 +411,72 @@ describe('M2MToken', () => {
  });
  });
 
+ async function createSignedM2MJwt(payload = mockM2MJwtPayload) {
+ const { data } = await signJwt(payload, signingJwks, {
+ algorithm: 'RS256',
+ header: { typ: 'JWT', kid: 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD' },
+ });
+ return data!;
+ }
+
+ describe('verify — JWT format', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date(mockJwtPayload.iat * 1000));
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('verifies a JWT M2M token using secretKey (JWKS lookup)', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json(mockJwks)),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ const result = await m2mApi.verify({ token: jwtToken });
+
+ expect(result.id).toBe('mt_2xKa9Bgv7NxMRDFyQw8LpZ3cTmU1vHjE');
+ expect(result.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
+ expect(result.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+ });
+
+ it('throws when JWT signature cannot be verified', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json({ keys: [] })),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow();
+ });
+
+ it('throws when no secretKey or jwtKey is provided', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { apiUrl: 'https://api.clerk.test' },
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow('Failed to resolve JWK during verification');
+ });
+ });
+
  describe('list', () => {
  const machineId = 'mch_1xxxxxxxxxxxxx';
  const mockM2MTokenList = {

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,13 +1,25 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
+import { MachineTokenVerificationError, MachineTokenVerificationErrorCode } from '../../errors';
+import { decodeJwt } from '../../jwt/verifyJwt';
+import type { JwtMachineVerifyOptions } from '../../jwt/verifyMachineJwt';
+import { verifyM2MJwt } from '../../jwt/verifyMachineJwt';
+import { isM2MJwt } from '../../tokens/machine';
 import { joinPaths } from '../../util/path';
-import type { ClerkBackendApiRequestOptions } from '../request';
+import type { ClerkBackendApiRequestOptions, RequestFunction } from '../request';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+/**
+ * Format of the M2M token to create.
+ * - 'opaque': Opaque token with mt_ prefix
+ * - 'jwt': JWT signed with instance keys
+ */
+export type M2MTokenFormat = 'opaque' | 'jwt';
+
 type GetM2MTokenListParams = ClerkPaginationRequest<{
  /**
  * The machine ID to query machine-to-machine tokens by
@@ -39,6 +51,10 @@ type CreateM2MTokenParams = {
  */
  secondsUntilExpiration?: number | null;
  claims?: Record<string, unknown> | null;
+ /**
+ * @default 'opaque'
+ */
+ tokenFormat?: M2MTokenFormat;
 };
 
 type RevokeM2MTokenParams = {
@@ -65,6 +81,18 @@ type VerifyM2MTokenParams = {
 };
 
 export class M2MTokenApi extends AbstractAPI {
+ #verifyOptions: JwtMachineVerifyOptions;
+
+ /**
+ * @param verifyOptions - JWT verification options (secretKey, apiUrl, etc.).
+ * Passed explicitly because BuildRequestOptions are captured inside the buildRequest closure
+ * and are not accessible from the RequestFunction itself.
+ */
+ constructor(request: RequestFunction, verifyOptions: JwtMachineVerifyOptions = {}) {
+ super(request);
+ this.#verifyOptions = verifyOptions;
+ }
+
  #createRequestOptions(options: ClerkBackendApiRequestOptions, machineSecretKey?: string) {
  if (machineSecretKey) {
  return {
@@ -88,7 +116,7 @@ export class M2MTokenApi extends AbstractAPI {
  }
 
  async createToken(params?: CreateM2MTokenParams) {
- const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
+ const { claims = null, machineSecretKey, secondsUntilExpiration = null, tokenFormat = 'opaque' } = params || {};
 
  const requestOptions = this.#createRequestOptions(
  {
@@ -97,6 +125,7 @@ export class M2MTokenApi extends AbstractAPI {
  bodyParams: {
  secondsUntilExpiration,
  claims,
+ tokenFormat,
  },
  },
  machineSecretKey,
@@ -124,9 +153,35 @@ export class M2MTokenApi extends AbstractAPI {
  return this.request<M2MToken>(requestOptions);
  }
 
+ async #verifyJwtFormat(token: string): Promise<M2MToken> {
+ let decoded;
+ try {
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
+ }
+ decoded = data;
+ } catch (e) {
+ throw new MachineTokenVerificationError({
+ code: MachineTokenVerificationErrorCode.TokenInvalid,
+ message: (e as Error).message,
+ });
+ }
+
+ const result = await verifyM2MJwt(token, decoded, this.#verifyOptions);
+ if (result.errors) {
+ throw result.errors[0];
+ }
+ return result.data;
+ }
+
  async verify(params: VerifyM2MTokenParams) {
  const { token, machineSecretKey } = params;
 
+ if (isM2MJwt(token)) {
+ return this.#verifyJwtFormat(token);
+ }
+
  const requestOptions = this.#createRequestOptions(
  {
  method: 'POST',

.changeset/clever-ways-raise.md

@@ -0,0 +1,2 @@
+---
+---

integration/tests/machine-auth/m2m.test.ts

@@ -42,10 +42,9 @@ test.describe('machine-to-machine auth @machine', () => {
 
  app.get('/api/protected', async (req, res) => {
  const token = req.get('Authorization')?.split(' ')[1];
-
  try {
  const m2mToken = await clerkClient.m2m.verify({ token });
- res.send('Protected response ' + m2mToken.id);
+ res.send('Protected response ' + m2mToken.subject);
  } catch {
  res.status(401).send('Unauthorized');
  }
@@ -150,7 +149,7 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res.status()).toBe(200);
- expect(await res.text()).toBe('Protected response ' + emailServerM2MToken.id);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
 
  // Analytics server can access primary API server after adding scope
  await u.services.clerk.machines.createScope(analyticsServer.id, primaryApiServer.id);
@@ -165,9 +164,30 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res2.status()).toBe(200);
- expect(await res2.text()).toBe('Protected response ' + m2mToken.id);
+ expect(await res2.text()).toBe('Protected response ' + analyticsServer.id);
  await u.services.clerk.m2m.revokeToken({
  m2mTokenId: m2mToken.id,
  });
  });
+
+ test('verifies JWT format M2M token via local verification', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+
+ const client = createClerkClient({
+ secretKey: instanceKeys.get('with-api-keys').sk,
+ });
+ const jwtToken = await client.m2m.createToken({
+ machineSecretKey: emailServer.secretKey,
+ secondsUntilExpiration: 60 * 30,
+ tokenFormat: 'jwt',
+ });
+
+ const res = await u.page.request.get(app.serverUrl + '/api/protected', {
+ headers: { Authorization: `Bearer ${jwtToken.token}` },
+ });
+ expect(res.status()).toBe(200);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
+ // JWT-format tokens are self-contained and not stored in BAPI, so revocation
+ // is not applicable — they expire naturally via the exp claim.
+ });
 });

packages/backend/src/__tests__/exports.test.ts

@@ -49,11 +49,9 @@ describe('subpath /internal exports', () => {
  "decorateObjectWithResources",
  "getAuthObjectForAcceptedToken",
  "getAuthObjectFromJwt",
- "getMachineTokenType",
  "invalidTokenAuthObject",
  "isMachineToken",
  "isMachineTokenByPrefix",
- "isMachineTokenType",
  "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -1,8 +1,12 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { mockJwks, mockJwtPayload, mockM2MJwtPayload, signingJwks } from '../../fixtures';
+import { signJwt } from '../../jwt/signJwt';
 import { server, validateHeaders } from '../../mock-server';
+import { M2MTokenApi } from '../endpoints/M2MTokenApi';
 import { createBackendApiClient } from '../factory';
+import { buildRequest } from '../request';
 
 describe('M2MToken', () => {
  const m2mId = 'mt_1xxxxxxxxxxxxx';
@@ -110,6 +114,130 @@ describe('M2MToken', () => {
  'The provided Machine Secret Key is invalid. Make sure that your Machine Secret Key is correct.',
  );
  });
+
+ it('creates a jwt format m2m token', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ return HttpResponse.json({
+ ...mockM2MToken,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJpYXQiOjE3NTM3NDMzMTYsImV4cCI6MTc1Mzc0NjkxNn0.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ });
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates a jwt m2m token with custom claims and scopes', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ const customClaims = {
+ role: 'service',
+ tier: 'gold',
+ };
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ expect(body.claims).toEqual(customClaims);
+ return HttpResponse.json({
+ ...mockM2MToken,
+ claims: customClaims,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJyb2xlIjoic2VydmljZSIsInRpZXIiOiJnb2xkIiwiaWF0IjoxNzUzNzQzMzE2LCJleHAiOjE3NTM3NDY5MTZ9.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ claims: customClaims,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.claims).toEqual(customClaims);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates an opaque format m2m token when explicitly specified', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'opaque',
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ expect(response.token).toMatch(/^mt_.+$/);
+ });
+
+ it('creates an opaque m2m token by default when tokenFormat is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ // tokenFormat defaults to 'opaque' when omitted
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ secondsUntilExpiration: 3600,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ });
  });
 
  describe('revoke', () => {
@@ -283,6 +411,72 @@ describe('M2MToken', () => {
  });
  });
 
+ async function createSignedM2MJwt(payload = mockM2MJwtPayload) {
+ const { data } = await signJwt(payload, signingJwks, {
+ algorithm: 'RS256',
+ header: { typ: 'JWT', kid: 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD' },
+ });
+ return data!;
+ }
+
+ describe('verify — JWT format', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date(mockJwtPayload.iat * 1000));
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('verifies a JWT M2M token using secretKey (JWKS lookup)', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json(mockJwks)),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ const result = await m2mApi.verify({ token: jwtToken });
+
+ expect(result.id).toBe('mt_2xKa9Bgv7NxMRDFyQw8LpZ3cTmU1vHjE');
+ expect(result.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
+ expect(result.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+ });
+
+ it('throws when JWT signature cannot be verified', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json({ keys: [] })),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow();
+ });
+
+ it('throws when no secretKey or jwtKey is provided', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { apiUrl: 'https://api.clerk.test' },
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow('Failed to resolve JWK during verification');
+ });
+ });
+
  describe('list', () => {
  const machineId = 'mch_1xxxxxxxxxxxxx';
  const mockM2MTokenList = {

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,13 +1,25 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
+import { MachineTokenVerificationError, MachineTokenVerificationErrorCode } from '../../errors';
+import { decodeJwt } from '../../jwt/verifyJwt';
+import type { JwtMachineVerifyOptions } from '../../jwt/verifyMachineJwt';
+import { verifyM2MJwt } from '../../jwt/verifyMachineJwt';
+import { isM2MJwt } from '../../tokens/machine';
 import { joinPaths } from '../../util/path';
-import type { ClerkBackendApiRequestOptions } from '../request';
+import type { ClerkBackendApiRequestOptions, RequestFunction } from '../request';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+/**
+ * Format of the M2M token to create.
+ * - 'opaque': Opaque token with mt_ prefix
+ * - 'jwt': JWT signed with instance keys
+ */
+export type M2MTokenFormat = 'opaque' | 'jwt';
+
 type GetM2MTokenListParams = ClerkPaginationRequest<{
  /**
  * The machine ID to query machine-to-machine tokens by
@@ -39,6 +51,10 @@ type CreateM2MTokenParams = {
  */
  secondsUntilExpiration?: number | null;
  claims?: Record<string, unknown> | null;
+ /**
+ * @default 'opaque'
+ */
+ tokenFormat?: M2MTokenFormat;
 };
 
 type RevokeM2MTokenParams = {
@@ -65,6 +81,18 @@ type VerifyM2MTokenParams = {
 };
 
 export class M2MTokenApi extends AbstractAPI {
+ #verifyOptions: JwtMachineVerifyOptions;
+
+ /**
+ * @param verifyOptions - JWT verification options (secretKey, apiUrl, etc.).
+ * Passed explicitly because BuildRequestOptions are captured inside the buildRequest closure
+ * and are not accessible from the RequestFunction itself.
+ */
+ constructor(request: RequestFunction, verifyOptions: JwtMachineVerifyOptions = {}) {
+ super(request);
+ this.#verifyOptions = verifyOptions;
+ }
+
  #createRequestOptions(options: ClerkBackendApiRequestOptions, machineSecretKey?: string) {
  if (machineSecretKey) {
  return {
@@ -88,7 +116,7 @@ export class M2MTokenApi extends AbstractAPI {
  }
 
  async createToken(params?: CreateM2MTokenParams) {
- const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
+ const { claims = null, machineSecretKey, secondsUntilExpiration = null, tokenFormat = 'opaque' } = params || {};
 
  const requestOptions = this.#createRequestOptions(
  {
@@ -97,6 +125,7 @@ export class M2MTokenApi extends AbstractAPI {
  bodyParams: {
  secondsUntilExpiration,
  claims,
+ tokenFormat,
  },
  },
  machineSecretKey,
@@ -124,9 +153,35 @@ export class M2MTokenApi extends AbstractAPI {
  return this.request<M2MToken>(requestOptions);
  }
 
+ async #verifyJwtFormat(token: string): Promise<M2MToken> {
+ let decoded;
+ try {
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
+ }
+ decoded = data;
+ } catch (e) {
+ throw new MachineTokenVerificationError({
+ code: MachineTokenVerificationErrorCode.TokenInvalid,
+ message: (e as Error).message,
+ });
+ }
+
+ const result = await verifyM2MJwt(token, decoded, this.#verifyOptions);
+ if (result.errors) {
+ throw result.errors[0];
+ }
+ return result.data;
+ }
+
  async verify(params: VerifyM2MTokenParams) {
  const { token, machineSecretKey } = params;
 
+ if (isM2MJwt(token)) {
+ return this.#verifyJwtFormat(token);
+ }
+
  const requestOptions = this.#createRequestOptions(
  {
  method: 'POST',

.changeset/clever-ways-raise.md

@@ -0,0 +1,2 @@
+---
+---

integration/tests/machine-auth/m2m.test.ts

@@ -42,10 +42,9 @@ test.describe('machine-to-machine auth @machine', () => {
 
  app.get('/api/protected', async (req, res) => {
  const token = req.get('Authorization')?.split(' ')[1];
-
  try {
  const m2mToken = await clerkClient.m2m.verify({ token });
- res.send('Protected response ' + m2mToken.id);
+ res.send('Protected response ' + m2mToken.subject);
  } catch {
  res.status(401).send('Unauthorized');
  }
@@ -150,7 +149,7 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res.status()).toBe(200);
- expect(await res.text()).toBe('Protected response ' + emailServerM2MToken.id);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
 
  // Analytics server can access primary API server after adding scope
  await u.services.clerk.machines.createScope(analyticsServer.id, primaryApiServer.id);
@@ -165,9 +164,30 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res2.status()).toBe(200);
- expect(await res2.text()).toBe('Protected response ' + m2mToken.id);
+ expect(await res2.text()).toBe('Protected response ' + analyticsServer.id);
  await u.services.clerk.m2m.revokeToken({
  m2mTokenId: m2mToken.id,
  });
  });
+
+ test('verifies JWT format M2M token via local verification', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+
+ const client = createClerkClient({
+ secretKey: instanceKeys.get('with-api-keys').sk,
+ });
+ const jwtToken = await client.m2m.createToken({
+ machineSecretKey: emailServer.secretKey,
+ secondsUntilExpiration: 60 * 30,
+ tokenFormat: 'jwt',
+ });
+
+ const res = await u.page.request.get(app.serverUrl + '/api/protected', {
+ headers: { Authorization: `Bearer ${jwtToken.token}` },
+ });
+ expect(res.status()).toBe(200);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
+ // JWT-format tokens are self-contained and not stored in BAPI, so revocation
+ // is not applicable — they expire naturally via the exp claim.
+ });
 });

packages/backend/src/__tests__/exports.test.ts

@@ -49,11 +49,9 @@ describe('subpath /internal exports', () => {
  "decorateObjectWithResources",
  "getAuthObjectForAcceptedToken",
  "getAuthObjectFromJwt",
- "getMachineTokenType",
  "invalidTokenAuthObject",
  "isMachineToken",
  "isMachineTokenByPrefix",
- "isMachineTokenType",
  "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -1,8 +1,12 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { mockJwks, mockJwtPayload, mockM2MJwtPayload, signingJwks } from '../../fixtures';
+import { signJwt } from '../../jwt/signJwt';
 import { server, validateHeaders } from '../../mock-server';
+import { M2MTokenApi } from '../endpoints/M2MTokenApi';
 import { createBackendApiClient } from '../factory';
+import { buildRequest } from '../request';
 
 describe('M2MToken', () => {
  const m2mId = 'mt_1xxxxxxxxxxxxx';
@@ -110,6 +114,130 @@ describe('M2MToken', () => {
  'The provided Machine Secret Key is invalid. Make sure that your Machine Secret Key is correct.',
  );
  });
+
+ it('creates a jwt format m2m token', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ return HttpResponse.json({
+ ...mockM2MToken,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJpYXQiOjE3NTM3NDMzMTYsImV4cCI6MTc1Mzc0NjkxNn0.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ });
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates a jwt m2m token with custom claims and scopes', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ const customClaims = {
+ role: 'service',
+ tier: 'gold',
+ };
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ expect(body.claims).toEqual(customClaims);
+ return HttpResponse.json({
+ ...mockM2MToken,
+ claims: customClaims,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJyb2xlIjoic2VydmljZSIsInRpZXIiOiJnb2xkIiwiaWF0IjoxNzUzNzQzMzE2LCJleHAiOjE3NTM3NDY5MTZ9.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ claims: customClaims,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.claims).toEqual(customClaims);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates an opaque format m2m token when explicitly specified', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'opaque',
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ expect(response.token).toMatch(/^mt_.+$/);
+ });
+
+ it('creates an opaque m2m token by default when tokenFormat is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ // tokenFormat defaults to 'opaque' when omitted
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ secondsUntilExpiration: 3600,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ });
  });
 
  describe('revoke', () => {
@@ -283,6 +411,72 @@ describe('M2MToken', () => {
  });
  });
 
+ async function createSignedM2MJwt(payload = mockM2MJwtPayload) {
+ const { data } = await signJwt(payload, signingJwks, {
+ algorithm: 'RS256',
+ header: { typ: 'JWT', kid: 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD' },
+ });
+ return data!;
+ }
+
+ describe('verify — JWT format', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date(mockJwtPayload.iat * 1000));
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('verifies a JWT M2M token using secretKey (JWKS lookup)', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json(mockJwks)),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ const result = await m2mApi.verify({ token: jwtToken });
+
+ expect(result.id).toBe('mt_2xKa9Bgv7NxMRDFyQw8LpZ3cTmU1vHjE');
+ expect(result.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
+ expect(result.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+ });
+
+ it('throws when JWT signature cannot be verified', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json({ keys: [] })),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow();
+ });
+
+ it('throws when no secretKey or jwtKey is provided', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { apiUrl: 'https://api.clerk.test' },
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow('Failed to resolve JWK during verification');
+ });
+ });
+
  describe('list', () => {
  const machineId = 'mch_1xxxxxxxxxxxxx';
  const mockM2MTokenList = {

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,13 +1,25 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
+import { MachineTokenVerificationError, MachineTokenVerificationErrorCode } from '../../errors';
+import { decodeJwt } from '../../jwt/verifyJwt';
+import type { JwtMachineVerifyOptions } from '../../jwt/verifyMachineJwt';
+import { verifyM2MJwt } from '../../jwt/verifyMachineJwt';
+import { isM2MJwt } from '../../tokens/machine';
 import { joinPaths } from '../../util/path';
-import type { ClerkBackendApiRequestOptions } from '../request';
+import type { ClerkBackendApiRequestOptions, RequestFunction } from '../request';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+/**
+ * Format of the M2M token to create.
+ * - 'opaque': Opaque token with mt_ prefix
+ * - 'jwt': JWT signed with instance keys
+ */
+export type M2MTokenFormat = 'opaque' | 'jwt';
+
 type GetM2MTokenListParams = ClerkPaginationRequest<{
  /**
  * The machine ID to query machine-to-machine tokens by
@@ -39,6 +51,10 @@ type CreateM2MTokenParams = {
  */
  secondsUntilExpiration?: number | null;
  claims?: Record<string, unknown> | null;
+ /**
+ * @default 'opaque'
+ */
+ tokenFormat?: M2MTokenFormat;
 };
 
 type RevokeM2MTokenParams = {
@@ -65,6 +81,18 @@ type VerifyM2MTokenParams = {
 };
 
 export class M2MTokenApi extends AbstractAPI {
+ #verifyOptions: JwtMachineVerifyOptions;
+
+ /**
+ * @param verifyOptions - JWT verification options (secretKey, apiUrl, etc.).
+ * Passed explicitly because BuildRequestOptions are captured inside the buildRequest closure
+ * and are not accessible from the RequestFunction itself.
+ */
+ constructor(request: RequestFunction, verifyOptions: JwtMachineVerifyOptions = {}) {
+ super(request);
+ this.#verifyOptions = verifyOptions;
+ }
+
  #createRequestOptions(options: ClerkBackendApiRequestOptions, machineSecretKey?: string) {
  if (machineSecretKey) {
  return {
@@ -88,7 +116,7 @@ export class M2MTokenApi extends AbstractAPI {
  }
 
  async createToken(params?: CreateM2MTokenParams) {
- const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
+ const { claims = null, machineSecretKey, secondsUntilExpiration = null, tokenFormat = 'opaque' } = params || {};
 
  const requestOptions = this.#createRequestOptions(
  {
@@ -97,6 +125,7 @@ export class M2MTokenApi extends AbstractAPI {
  bodyParams: {
  secondsUntilExpiration,
  claims,
+ tokenFormat,
  },
  },
  machineSecretKey,
@@ -124,9 +153,35 @@ export class M2MTokenApi extends AbstractAPI {
  return this.request<M2MToken>(requestOptions);
  }
 
+ async #verifyJwtFormat(token: string): Promise<M2MToken> {
+ let decoded;
+ try {
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
+ }
+ decoded = data;
+ } catch (e) {
+ throw new MachineTokenVerificationError({
+ code: MachineTokenVerificationErrorCode.TokenInvalid,
+ message: (e as Error).message,
+ });
+ }
+
+ const result = await verifyM2MJwt(token, decoded, this.#verifyOptions);
+ if (result.errors) {
+ throw result.errors[0];
+ }
+ return result.data;
+ }
+
  async verify(params: VerifyM2MTokenParams) {
  const { token, machineSecretKey } = params;
 
+ if (isM2MJwt(token)) {
+ return this.#verifyJwtFormat(token);
+ }
+
  const requestOptions = this.#createRequestOptions(
  {
  method: 'POST',

.changeset/clever-ways-raise.md

@@ -0,0 +1,2 @@
+---
+---

integration/tests/machine-auth/m2m.test.ts

@@ -42,10 +42,9 @@ test.describe('machine-to-machine auth @machine', () => {
 
  app.get('/api/protected', async (req, res) => {
  const token = req.get('Authorization')?.split(' ')[1];
-
  try {
  const m2mToken = await clerkClient.m2m.verify({ token });
- res.send('Protected response ' + m2mToken.id);
+ res.send('Protected response ' + m2mToken.subject);
  } catch {
  res.status(401).send('Unauthorized');
  }
@@ -150,7 +149,7 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res.status()).toBe(200);
- expect(await res.text()).toBe('Protected response ' + emailServerM2MToken.id);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
 
  // Analytics server can access primary API server after adding scope
  await u.services.clerk.machines.createScope(analyticsServer.id, primaryApiServer.id);
@@ -165,9 +164,30 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res2.status()).toBe(200);
- expect(await res2.text()).toBe('Protected response ' + m2mToken.id);
+ expect(await res2.text()).toBe('Protected response ' + analyticsServer.id);
  await u.services.clerk.m2m.revokeToken({
  m2mTokenId: m2mToken.id,
  });
  });
+
+ test('verifies JWT format M2M token via local verification', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+
+ const client = createClerkClient({
+ secretKey: instanceKeys.get('with-api-keys').sk,
+ });
+ const jwtToken = await client.m2m.createToken({
+ machineSecretKey: emailServer.secretKey,
+ secondsUntilExpiration: 60 * 30,
+ tokenFormat: 'jwt',
+ });
+
+ const res = await u.page.request.get(app.serverUrl + '/api/protected', {
+ headers: { Authorization: `Bearer ${jwtToken.token}` },
+ });
+ expect(res.status()).toBe(200);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
+ // JWT-format tokens are self-contained and not stored in BAPI, so revocation
+ // is not applicable — they expire naturally via the exp claim.
+ });
 });

packages/backend/src/__tests__/exports.test.ts

@@ -49,11 +49,9 @@ describe('subpath /internal exports', () => {
  "decorateObjectWithResources",
  "getAuthObjectForAcceptedToken",
  "getAuthObjectFromJwt",
- "getMachineTokenType",
  "invalidTokenAuthObject",
  "isMachineToken",
  "isMachineTokenByPrefix",
- "isMachineTokenType",
  "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -1,8 +1,12 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { mockJwks, mockJwtPayload, mockM2MJwtPayload, signingJwks } from '../../fixtures';
+import { signJwt } from '../../jwt/signJwt';
 import { server, validateHeaders } from '../../mock-server';
+import { M2MTokenApi } from '../endpoints/M2MTokenApi';
 import { createBackendApiClient } from '../factory';
+import { buildRequest } from '../request';
 
 describe('M2MToken', () => {
  const m2mId = 'mt_1xxxxxxxxxxxxx';
@@ -110,6 +114,130 @@ describe('M2MToken', () => {
  'The provided Machine Secret Key is invalid. Make sure that your Machine Secret Key is correct.',
  );
  });
+
+ it('creates a jwt format m2m token', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ return HttpResponse.json({
+ ...mockM2MToken,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJpYXQiOjE3NTM3NDMzMTYsImV4cCI6MTc1Mzc0NjkxNn0.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ });
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates a jwt m2m token with custom claims and scopes', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ const customClaims = {
+ role: 'service',
+ tier: 'gold',
+ };
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ expect(body.claims).toEqual(customClaims);
+ return HttpResponse.json({
+ ...mockM2MToken,
+ claims: customClaims,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJyb2xlIjoic2VydmljZSIsInRpZXIiOiJnb2xkIiwiaWF0IjoxNzUzNzQzMzE2LCJleHAiOjE3NTM3NDY5MTZ9.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ claims: customClaims,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.claims).toEqual(customClaims);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates an opaque format m2m token when explicitly specified', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'opaque',
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ expect(response.token).toMatch(/^mt_.+$/);
+ });
+
+ it('creates an opaque m2m token by default when tokenFormat is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ // tokenFormat defaults to 'opaque' when omitted
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ secondsUntilExpiration: 3600,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ });
  });
 
  describe('revoke', () => {
@@ -283,6 +411,72 @@ describe('M2MToken', () => {
  });
  });
 
+ async function createSignedM2MJwt(payload = mockM2MJwtPayload) {
+ const { data } = await signJwt(payload, signingJwks, {
+ algorithm: 'RS256',
+ header: { typ: 'JWT', kid: 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD' },
+ });
+ return data!;
+ }
+
+ describe('verify — JWT format', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date(mockJwtPayload.iat * 1000));
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('verifies a JWT M2M token using secretKey (JWKS lookup)', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json(mockJwks)),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ const result = await m2mApi.verify({ token: jwtToken });
+
+ expect(result.id).toBe('mt_2xKa9Bgv7NxMRDFyQw8LpZ3cTmU1vHjE');
+ expect(result.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
+ expect(result.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+ });
+
+ it('throws when JWT signature cannot be verified', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json({ keys: [] })),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow();
+ });
+
+ it('throws when no secretKey or jwtKey is provided', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { apiUrl: 'https://api.clerk.test' },
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow('Failed to resolve JWK during verification');
+ });
+ });
+
  describe('list', () => {
  const machineId = 'mch_1xxxxxxxxxxxxx';
  const mockM2MTokenList = {

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,13 +1,25 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
+import { MachineTokenVerificationError, MachineTokenVerificationErrorCode } from '../../errors';
+import { decodeJwt } from '../../jwt/verifyJwt';
+import type { JwtMachineVerifyOptions } from '../../jwt/verifyMachineJwt';
+import { verifyM2MJwt } from '../../jwt/verifyMachineJwt';
+import { isM2MJwt } from '../../tokens/machine';
 import { joinPaths } from '../../util/path';
-import type { ClerkBackendApiRequestOptions } from '../request';
+import type { ClerkBackendApiRequestOptions, RequestFunction } from '../request';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+/**
+ * Format of the M2M token to create.
+ * - 'opaque': Opaque token with mt_ prefix
+ * - 'jwt': JWT signed with instance keys
+ */
+export type M2MTokenFormat = 'opaque' | 'jwt';
+
 type GetM2MTokenListParams = ClerkPaginationRequest<{
  /**
  * The machine ID to query machine-to-machine tokens by
@@ -39,6 +51,10 @@ type CreateM2MTokenParams = {
  */
  secondsUntilExpiration?: number | null;
  claims?: Record<string, unknown> | null;
+ /**
+ * @default 'opaque'
+ */
+ tokenFormat?: M2MTokenFormat;
 };
 
 type RevokeM2MTokenParams = {
@@ -65,6 +81,18 @@ type VerifyM2MTokenParams = {
 };
 
 export class M2MTokenApi extends AbstractAPI {
+ #verifyOptions: JwtMachineVerifyOptions;
+
+ /**
+ * @param verifyOptions - JWT verification options (secretKey, apiUrl, etc.).
+ * Passed explicitly because BuildRequestOptions are captured inside the buildRequest closure
+ * and are not accessible from the RequestFunction itself.
+ */
+ constructor(request: RequestFunction, verifyOptions: JwtMachineVerifyOptions = {}) {
+ super(request);
+ this.#verifyOptions = verifyOptions;
+ }
+
  #createRequestOptions(options: ClerkBackendApiRequestOptions, machineSecretKey?: string) {
  if (machineSecretKey) {
  return {
@@ -88,7 +116,7 @@ export class M2MTokenApi extends AbstractAPI {
  }
 
  async createToken(params?: CreateM2MTokenParams) {
- const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
+ const { claims = null, machineSecretKey, secondsUntilExpiration = null, tokenFormat = 'opaque' } = params || {};
 
  const requestOptions = this.#createRequestOptions(
  {
@@ -97,6 +125,7 @@ export class M2MTokenApi extends AbstractAPI {
  bodyParams: {
  secondsUntilExpiration,
  claims,
+ tokenFormat,
  },
  },
  machineSecretKey,
@@ -124,9 +153,35 @@ export class M2MTokenApi extends AbstractAPI {
  return this.request<M2MToken>(requestOptions);
  }
 
+ async #verifyJwtFormat(token: string): Promise<M2MToken> {
+ let decoded;
+ try {
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
+ }
+ decoded = data;
+ } catch (e) {
+ throw new MachineTokenVerificationError({
+ code: MachineTokenVerificationErrorCode.TokenInvalid,
+ message: (e as Error).message,
+ });
+ }
+
+ const result = await verifyM2MJwt(token, decoded, this.#verifyOptions);
+ if (result.errors) {
+ throw result.errors[0];
+ }
+ return result.data;
+ }
+
  async verify(params: VerifyM2MTokenParams) {
  const { token, machineSecretKey } = params;
 
+ if (isM2MJwt(token)) {
+ return this.#verifyJwtFormat(token);
+ }
+
  const requestOptions = this.#createRequestOptions(
  {
  method: 'POST',

.changeset/clever-ways-raise.md

@@ -0,0 +1,2 @@
+---
+---

integration/tests/machine-auth/m2m.test.ts

@@ -42,10 +42,9 @@ test.describe('machine-to-machine auth @machine', () => {
 
  app.get('/api/protected', async (req, res) => {
  const token = req.get('Authorization')?.split(' ')[1];
-
  try {
  const m2mToken = await clerkClient.m2m.verify({ token });
- res.send('Protected response ' + m2mToken.id);
+ res.send('Protected response ' + m2mToken.subject);
  } catch {
  res.status(401).send('Unauthorized');
  }
@@ -150,7 +149,7 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res.status()).toBe(200);
- expect(await res.text()).toBe('Protected response ' + emailServerM2MToken.id);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
 
  // Analytics server can access primary API server after adding scope
  await u.services.clerk.machines.createScope(analyticsServer.id, primaryApiServer.id);
@@ -165,9 +164,30 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res2.status()).toBe(200);
- expect(await res2.text()).toBe('Protected response ' + m2mToken.id);
+ expect(await res2.text()).toBe('Protected response ' + analyticsServer.id);
  await u.services.clerk.m2m.revokeToken({
  m2mTokenId: m2mToken.id,
  });
  });
+
+ test('verifies JWT format M2M token via local verification', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+
+ const client = createClerkClient({
+ secretKey: instanceKeys.get('with-api-keys').sk,
+ });
+ const jwtToken = await client.m2m.createToken({
+ machineSecretKey: emailServer.secretKey,
+ secondsUntilExpiration: 60 * 30,
+ tokenFormat: 'jwt',
+ });
+
+ const res = await u.page.request.get(app.serverUrl + '/api/protected', {
+ headers: { Authorization: `Bearer ${jwtToken.token}` },
+ });
+ expect(res.status()).toBe(200);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
+ // JWT-format tokens are self-contained and not stored in BAPI, so revocation
+ // is not applicable — they expire naturally via the exp claim.
+ });
 });

packages/backend/src/__tests__/exports.test.ts

@@ -49,11 +49,9 @@ describe('subpath /internal exports', () => {
  "decorateObjectWithResources",
  "getAuthObjectForAcceptedToken",
  "getAuthObjectFromJwt",
- "getMachineTokenType",
  "invalidTokenAuthObject",
  "isMachineToken",
  "isMachineTokenByPrefix",
- "isMachineTokenType",
  "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -1,8 +1,12 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { mockJwks, mockJwtPayload, mockM2MJwtPayload, signingJwks } from '../../fixtures';
+import { signJwt } from '../../jwt/signJwt';
 import { server, validateHeaders } from '../../mock-server';
+import { M2MTokenApi } from '../endpoints/M2MTokenApi';
 import { createBackendApiClient } from '../factory';
+import { buildRequest } from '../request';
 
 describe('M2MToken', () => {
  const m2mId = 'mt_1xxxxxxxxxxxxx';
@@ -110,6 +114,130 @@ describe('M2MToken', () => {
  'The provided Machine Secret Key is invalid. Make sure that your Machine Secret Key is correct.',
  );
  });
+
+ it('creates a jwt format m2m token', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ return HttpResponse.json({
+ ...mockM2MToken,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJpYXQiOjE3NTM3NDMzMTYsImV4cCI6MTc1Mzc0NjkxNn0.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ });
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates a jwt m2m token with custom claims and scopes', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ const customClaims = {
+ role: 'service',
+ tier: 'gold',
+ };
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ expect(body.claims).toEqual(customClaims);
+ return HttpResponse.json({
+ ...mockM2MToken,
+ claims: customClaims,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJyb2xlIjoic2VydmljZSIsInRpZXIiOiJnb2xkIiwiaWF0IjoxNzUzNzQzMzE2LCJleHAiOjE3NTM3NDY5MTZ9.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ claims: customClaims,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.claims).toEqual(customClaims);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates an opaque format m2m token when explicitly specified', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'opaque',
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ expect(response.token).toMatch(/^mt_.+$/);
+ });
+
+ it('creates an opaque m2m token by default when tokenFormat is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ // tokenFormat defaults to 'opaque' when omitted
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ secondsUntilExpiration: 3600,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ });
  });
 
  describe('revoke', () => {
@@ -283,6 +411,72 @@ describe('M2MToken', () => {
  });
  });
 
+ async function createSignedM2MJwt(payload = mockM2MJwtPayload) {
+ const { data } = await signJwt(payload, signingJwks, {
+ algorithm: 'RS256',
+ header: { typ: 'JWT', kid: 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD' },
+ });
+ return data!;
+ }
+
+ describe('verify — JWT format', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date(mockJwtPayload.iat * 1000));
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('verifies a JWT M2M token using secretKey (JWKS lookup)', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json(mockJwks)),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ const result = await m2mApi.verify({ token: jwtToken });
+
+ expect(result.id).toBe('mt_2xKa9Bgv7NxMRDFyQw8LpZ3cTmU1vHjE');
+ expect(result.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
+ expect(result.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+ });
+
+ it('throws when JWT signature cannot be verified', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json({ keys: [] })),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow();
+ });
+
+ it('throws when no secretKey or jwtKey is provided', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { apiUrl: 'https://api.clerk.test' },
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow('Failed to resolve JWK during verification');
+ });
+ });
+
  describe('list', () => {
  const machineId = 'mch_1xxxxxxxxxxxxx';
  const mockM2MTokenList = {

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,13 +1,25 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
+import { MachineTokenVerificationError, MachineTokenVerificationErrorCode } from '../../errors';
+import { decodeJwt } from '../../jwt/verifyJwt';
+import type { JwtMachineVerifyOptions } from '../../jwt/verifyMachineJwt';
+import { verifyM2MJwt } from '../../jwt/verifyMachineJwt';
+import { isM2MJwt } from '../../tokens/machine';
 import { joinPaths } from '../../util/path';
-import type { ClerkBackendApiRequestOptions } from '../request';
+import type { ClerkBackendApiRequestOptions, RequestFunction } from '../request';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+/**
+ * Format of the M2M token to create.
+ * - 'opaque': Opaque token with mt_ prefix
+ * - 'jwt': JWT signed with instance keys
+ */
+export type M2MTokenFormat = 'opaque' | 'jwt';
+
 type GetM2MTokenListParams = ClerkPaginationRequest<{
  /**
  * The machine ID to query machine-to-machine tokens by
@@ -39,6 +51,10 @@ type CreateM2MTokenParams = {
  */
  secondsUntilExpiration?: number | null;
  claims?: Record<string, unknown> | null;
+ /**
+ * @default 'opaque'
+ */
+ tokenFormat?: M2MTokenFormat;
 };
 
 type RevokeM2MTokenParams = {
@@ -65,6 +81,18 @@ type VerifyM2MTokenParams = {
 };
 
 export class M2MTokenApi extends AbstractAPI {
+ #verifyOptions: JwtMachineVerifyOptions;
+
+ /**
+ * @param verifyOptions - JWT verification options (secretKey, apiUrl, etc.).
+ * Passed explicitly because BuildRequestOptions are captured inside the buildRequest closure
+ * and are not accessible from the RequestFunction itself.
+ */
+ constructor(request: RequestFunction, verifyOptions: JwtMachineVerifyOptions = {}) {
+ super(request);
+ this.#verifyOptions = verifyOptions;
+ }
+
  #createRequestOptions(options: ClerkBackendApiRequestOptions, machineSecretKey?: string) {
  if (machineSecretKey) {
  return {
@@ -88,7 +116,7 @@ export class M2MTokenApi extends AbstractAPI {
  }
 
  async createToken(params?: CreateM2MTokenParams) {
- const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
+ const { claims = null, machineSecretKey, secondsUntilExpiration = null, tokenFormat = 'opaque' } = params || {};
 
  const requestOptions = this.#createRequestOptions(
  {
@@ -97,6 +125,7 @@ export class M2MTokenApi extends AbstractAPI {
  bodyParams: {
  secondsUntilExpiration,
  claims,
+ tokenFormat,
  },
  },
  machineSecretKey,
@@ -124,9 +153,35 @@ export class M2MTokenApi extends AbstractAPI {
  return this.request<M2MToken>(requestOptions);
  }
 
+ async #verifyJwtFormat(token: string): Promise<M2MToken> {
+ let decoded;
+ try {
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
+ }
+ decoded = data;
+ } catch (e) {
+ throw new MachineTokenVerificationError({
+ code: MachineTokenVerificationErrorCode.TokenInvalid,
+ message: (e as Error).message,
+ });
+ }
+
+ const result = await verifyM2MJwt(token, decoded, this.#verifyOptions);
+ if (result.errors) {
+ throw result.errors[0];
+ }
+ return result.data;
+ }
+
  async verify(params: VerifyM2MTokenParams) {
  const { token, machineSecretKey } = params;
 
+ if (isM2MJwt(token)) {
+ return this.#verifyJwtFormat(token);
+ }
+
  const requestOptions = this.#createRequestOptions(
  {
  method: 'POST',

.changeset/clever-ways-raise.md

@@ -0,0 +1,2 @@
+---
+---

integration/tests/machine-auth/m2m.test.ts

@@ -42,10 +42,9 @@ test.describe('machine-to-machine auth @machine', () => {
 
  app.get('/api/protected', async (req, res) => {
  const token = req.get('Authorization')?.split(' ')[1];
-
  try {
  const m2mToken = await clerkClient.m2m.verify({ token });
- res.send('Protected response ' + m2mToken.id);
+ res.send('Protected response ' + m2mToken.subject);
  } catch {
  res.status(401).send('Unauthorized');
  }
@@ -150,7 +149,7 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res.status()).toBe(200);
- expect(await res.text()).toBe('Protected response ' + emailServerM2MToken.id);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
 
  // Analytics server can access primary API server after adding scope
  await u.services.clerk.machines.createScope(analyticsServer.id, primaryApiServer.id);
@@ -165,9 +164,30 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res2.status()).toBe(200);
- expect(await res2.text()).toBe('Protected response ' + m2mToken.id);
+ expect(await res2.text()).toBe('Protected response ' + analyticsServer.id);
  await u.services.clerk.m2m.revokeToken({
  m2mTokenId: m2mToken.id,
  });
  });
+
+ test('verifies JWT format M2M token via local verification', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+
+ const client = createClerkClient({
+ secretKey: instanceKeys.get('with-api-keys').sk,
+ });
+ const jwtToken = await client.m2m.createToken({
+ machineSecretKey: emailServer.secretKey,
+ secondsUntilExpiration: 60 * 30,
+ tokenFormat: 'jwt',
+ });
+
+ const res = await u.page.request.get(app.serverUrl + '/api/protected', {
+ headers: { Authorization: `Bearer ${jwtToken.token}` },
+ });
+ expect(res.status()).toBe(200);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
+ // JWT-format tokens are self-contained and not stored in BAPI, so revocation
+ // is not applicable — they expire naturally via the exp claim.
+ });
 });

packages/backend/src/__tests__/exports.test.ts

@@ -49,11 +49,9 @@ describe('subpath /internal exports', () => {
  "decorateObjectWithResources",
  "getAuthObjectForAcceptedToken",
  "getAuthObjectFromJwt",
- "getMachineTokenType",
  "invalidTokenAuthObject",
  "isMachineToken",
  "isMachineTokenByPrefix",
- "isMachineTokenType",
  "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -1,8 +1,12 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { mockJwks, mockJwtPayload, mockM2MJwtPayload, signingJwks } from '../../fixtures';
+import { signJwt } from '../../jwt/signJwt';
 import { server, validateHeaders } from '../../mock-server';
+import { M2MTokenApi } from '../endpoints/M2MTokenApi';
 import { createBackendApiClient } from '../factory';
+import { buildRequest } from '../request';
 
 describe('M2MToken', () => {
  const m2mId = 'mt_1xxxxxxxxxxxxx';
@@ -110,6 +114,130 @@ describe('M2MToken', () => {
  'The provided Machine Secret Key is invalid. Make sure that your Machine Secret Key is correct.',
  );
  });
+
+ it('creates a jwt format m2m token', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ return HttpResponse.json({
+ ...mockM2MToken,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJpYXQiOjE3NTM3NDMzMTYsImV4cCI6MTc1Mzc0NjkxNn0.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ });
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates a jwt m2m token with custom claims and scopes', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ const customClaims = {
+ role: 'service',
+ tier: 'gold',
+ };
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ expect(body.claims).toEqual(customClaims);
+ return HttpResponse.json({
+ ...mockM2MToken,
+ claims: customClaims,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJyb2xlIjoic2VydmljZSIsInRpZXIiOiJnb2xkIiwiaWF0IjoxNzUzNzQzMzE2LCJleHAiOjE3NTM3NDY5MTZ9.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ claims: customClaims,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.claims).toEqual(customClaims);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates an opaque format m2m token when explicitly specified', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'opaque',
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ expect(response.token).toMatch(/^mt_.+$/);
+ });
+
+ it('creates an opaque m2m token by default when tokenFormat is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ // tokenFormat defaults to 'opaque' when omitted
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ secondsUntilExpiration: 3600,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ });
  });
 
  describe('revoke', () => {
@@ -283,6 +411,72 @@ describe('M2MToken', () => {
  });
  });
 
+ async function createSignedM2MJwt(payload = mockM2MJwtPayload) {
+ const { data } = await signJwt(payload, signingJwks, {
+ algorithm: 'RS256',
+ header: { typ: 'JWT', kid: 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD' },
+ });
+ return data!;
+ }
+
+ describe('verify — JWT format', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date(mockJwtPayload.iat * 1000));
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('verifies a JWT M2M token using secretKey (JWKS lookup)', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json(mockJwks)),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ const result = await m2mApi.verify({ token: jwtToken });
+
+ expect(result.id).toBe('mt_2xKa9Bgv7NxMRDFyQw8LpZ3cTmU1vHjE');
+ expect(result.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
+ expect(result.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+ });
+
+ it('throws when JWT signature cannot be verified', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json({ keys: [] })),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow();
+ });
+
+ it('throws when no secretKey or jwtKey is provided', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { apiUrl: 'https://api.clerk.test' },
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow('Failed to resolve JWK during verification');
+ });
+ });
+
  describe('list', () => {
  const machineId = 'mch_1xxxxxxxxxxxxx';
  const mockM2MTokenList = {

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,13 +1,25 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
+import { MachineTokenVerificationError, MachineTokenVerificationErrorCode } from '../../errors';
+import { decodeJwt } from '../../jwt/verifyJwt';
+import type { JwtMachineVerifyOptions } from '../../jwt/verifyMachineJwt';
+import { verifyM2MJwt } from '../../jwt/verifyMachineJwt';
+import { isM2MJwt } from '../../tokens/machine';
 import { joinPaths } from '../../util/path';
-import type { ClerkBackendApiRequestOptions } from '../request';
+import type { ClerkBackendApiRequestOptions, RequestFunction } from '../request';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+/**
+ * Format of the M2M token to create.
+ * - 'opaque': Opaque token with mt_ prefix
+ * - 'jwt': JWT signed with instance keys
+ */
+export type M2MTokenFormat = 'opaque' | 'jwt';
+
 type GetM2MTokenListParams = ClerkPaginationRequest<{
  /**
  * The machine ID to query machine-to-machine tokens by
@@ -39,6 +51,10 @@ type CreateM2MTokenParams = {
  */
  secondsUntilExpiration?: number | null;
  claims?: Record<string, unknown> | null;
+ /**
+ * @default 'opaque'
+ */
+ tokenFormat?: M2MTokenFormat;
 };
 
 type RevokeM2MTokenParams = {
@@ -65,6 +81,18 @@ type VerifyM2MTokenParams = {
 };
 
 export class M2MTokenApi extends AbstractAPI {
+ #verifyOptions: JwtMachineVerifyOptions;
+
+ /**
+ * @param verifyOptions - JWT verification options (secretKey, apiUrl, etc.).
+ * Passed explicitly because BuildRequestOptions are captured inside the buildRequest closure
+ * and are not accessible from the RequestFunction itself.
+ */
+ constructor(request: RequestFunction, verifyOptions: JwtMachineVerifyOptions = {}) {
+ super(request);
+ this.#verifyOptions = verifyOptions;
+ }
+
  #createRequestOptions(options: ClerkBackendApiRequestOptions, machineSecretKey?: string) {
  if (machineSecretKey) {
  return {
@@ -88,7 +116,7 @@ export class M2MTokenApi extends AbstractAPI {
  }
 
  async createToken(params?: CreateM2MTokenParams) {
- const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
+ const { claims = null, machineSecretKey, secondsUntilExpiration = null, tokenFormat = 'opaque' } = params || {};
 
  const requestOptions = this.#createRequestOptions(
  {
@@ -97,6 +125,7 @@ export class M2MTokenApi extends AbstractAPI {
  bodyParams: {
  secondsUntilExpiration,
  claims,
+ tokenFormat,
  },
  },
  machineSecretKey,
@@ -124,9 +153,35 @@ export class M2MTokenApi extends AbstractAPI {
  return this.request<M2MToken>(requestOptions);
  }
 
+ async #verifyJwtFormat(token: string): Promise<M2MToken> {
+ let decoded;
+ try {
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
+ }
+ decoded = data;
+ } catch (e) {
+ throw new MachineTokenVerificationError({
+ code: MachineTokenVerificationErrorCode.TokenInvalid,
+ message: (e as Error).message,
+ });
+ }
+
+ const result = await verifyM2MJwt(token, decoded, this.#verifyOptions);
+ if (result.errors) {
+ throw result.errors[0];
+ }
+ return result.data;
+ }
+
  async verify(params: VerifyM2MTokenParams) {
  const { token, machineSecretKey } = params;
 
+ if (isM2MJwt(token)) {
+ return this.#verifyJwtFormat(token);
+ }
+
  const requestOptions = this.#createRequestOptions(
  {
  method: 'POST',

.changeset/clever-ways-raise.md

@@ -0,0 +1,2 @@
+---
+---

integration/tests/machine-auth/m2m.test.ts

@@ -42,10 +42,9 @@ test.describe('machine-to-machine auth @machine', () => {
 
  app.get('/api/protected', async (req, res) => {
  const token = req.get('Authorization')?.split(' ')[1];
-
  try {
  const m2mToken = await clerkClient.m2m.verify({ token });
- res.send('Protected response ' + m2mToken.id);
+ res.send('Protected response ' + m2mToken.subject);
  } catch {
  res.status(401).send('Unauthorized');
  }
@@ -150,7 +149,7 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res.status()).toBe(200);
- expect(await res.text()).toBe('Protected response ' + emailServerM2MToken.id);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
 
  // Analytics server can access primary API server after adding scope
  await u.services.clerk.machines.createScope(analyticsServer.id, primaryApiServer.id);
@@ -165,9 +164,30 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res2.status()).toBe(200);
- expect(await res2.text()).toBe('Protected response ' + m2mToken.id);
+ expect(await res2.text()).toBe('Protected response ' + analyticsServer.id);
  await u.services.clerk.m2m.revokeToken({
  m2mTokenId: m2mToken.id,
  });
  });
+
+ test('verifies JWT format M2M token via local verification', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+
+ const client = createClerkClient({
+ secretKey: instanceKeys.get('with-api-keys').sk,
+ });
+ const jwtToken = await client.m2m.createToken({
+ machineSecretKey: emailServer.secretKey,
+ secondsUntilExpiration: 60 * 30,
+ tokenFormat: 'jwt',
+ });
+
+ const res = await u.page.request.get(app.serverUrl + '/api/protected', {
+ headers: { Authorization: `Bearer ${jwtToken.token}` },
+ });
+ expect(res.status()).toBe(200);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
+ // JWT-format tokens are self-contained and not stored in BAPI, so revocation
+ // is not applicable — they expire naturally via the exp claim.
+ });
 });

packages/backend/src/__tests__/exports.test.ts

@@ -49,11 +49,9 @@ describe('subpath /internal exports', () => {
  "decorateObjectWithResources",
  "getAuthObjectForAcceptedToken",
  "getAuthObjectFromJwt",
- "getMachineTokenType",
  "invalidTokenAuthObject",
  "isMachineToken",
  "isMachineTokenByPrefix",
- "isMachineTokenType",
  "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -1,8 +1,12 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { mockJwks, mockJwtPayload, mockM2MJwtPayload, signingJwks } from '../../fixtures';
+import { signJwt } from '../../jwt/signJwt';
 import { server, validateHeaders } from '../../mock-server';
+import { M2MTokenApi } from '../endpoints/M2MTokenApi';
 import { createBackendApiClient } from '../factory';
+import { buildRequest } from '../request';
 
 describe('M2MToken', () => {
  const m2mId = 'mt_1xxxxxxxxxxxxx';
@@ -110,6 +114,130 @@ describe('M2MToken', () => {
  'The provided Machine Secret Key is invalid. Make sure that your Machine Secret Key is correct.',
  );
  });
+
+ it('creates a jwt format m2m token', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ return HttpResponse.json({
+ ...mockM2MToken,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJpYXQiOjE3NTM3NDMzMTYsImV4cCI6MTc1Mzc0NjkxNn0.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ });
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates a jwt m2m token with custom claims and scopes', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ const customClaims = {
+ role: 'service',
+ tier: 'gold',
+ };
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ expect(body.claims).toEqual(customClaims);
+ return HttpResponse.json({
+ ...mockM2MToken,
+ claims: customClaims,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJyb2xlIjoic2VydmljZSIsInRpZXIiOiJnb2xkIiwiaWF0IjoxNzUzNzQzMzE2LCJleHAiOjE3NTM3NDY5MTZ9.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ claims: customClaims,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.claims).toEqual(customClaims);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates an opaque format m2m token when explicitly specified', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'opaque',
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ expect(response.token).toMatch(/^mt_.+$/);
+ });
+
+ it('creates an opaque m2m token by default when tokenFormat is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ // tokenFormat defaults to 'opaque' when omitted
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ secondsUntilExpiration: 3600,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ });
  });
 
  describe('revoke', () => {
@@ -283,6 +411,72 @@ describe('M2MToken', () => {
  });
  });
 
+ async function createSignedM2MJwt(payload = mockM2MJwtPayload) {
+ const { data } = await signJwt(payload, signingJwks, {
+ algorithm: 'RS256',
+ header: { typ: 'JWT', kid: 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD' },
+ });
+ return data!;
+ }
+
+ describe('verify — JWT format', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date(mockJwtPayload.iat * 1000));
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('verifies a JWT M2M token using secretKey (JWKS lookup)', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json(mockJwks)),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ const result = await m2mApi.verify({ token: jwtToken });
+
+ expect(result.id).toBe('mt_2xKa9Bgv7NxMRDFyQw8LpZ3cTmU1vHjE');
+ expect(result.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
+ expect(result.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+ });
+
+ it('throws when JWT signature cannot be verified', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json({ keys: [] })),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow();
+ });
+
+ it('throws when no secretKey or jwtKey is provided', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { apiUrl: 'https://api.clerk.test' },
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow('Failed to resolve JWK during verification');
+ });
+ });
+
  describe('list', () => {
  const machineId = 'mch_1xxxxxxxxxxxxx';
  const mockM2MTokenList = {

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,13 +1,25 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
+import { MachineTokenVerificationError, MachineTokenVerificationErrorCode } from '../../errors';
+import { decodeJwt } from '../../jwt/verifyJwt';
+import type { JwtMachineVerifyOptions } from '../../jwt/verifyMachineJwt';
+import { verifyM2MJwt } from '../../jwt/verifyMachineJwt';
+import { isM2MJwt } from '../../tokens/machine';
 import { joinPaths } from '../../util/path';
-import type { ClerkBackendApiRequestOptions } from '../request';
+import type { ClerkBackendApiRequestOptions, RequestFunction } from '../request';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+/**
+ * Format of the M2M token to create.
+ * - 'opaque': Opaque token with mt_ prefix
+ * - 'jwt': JWT signed with instance keys
+ */
+export type M2MTokenFormat = 'opaque' | 'jwt';
+
 type GetM2MTokenListParams = ClerkPaginationRequest<{
  /**
  * The machine ID to query machine-to-machine tokens by
@@ -39,6 +51,10 @@ type CreateM2MTokenParams = {
  */
  secondsUntilExpiration?: number | null;
  claims?: Record<string, unknown> | null;
+ /**
+ * @default 'opaque'
+ */
+ tokenFormat?: M2MTokenFormat;
 };
 
 type RevokeM2MTokenParams = {
@@ -65,6 +81,18 @@ type VerifyM2MTokenParams = {
 };
 
 export class M2MTokenApi extends AbstractAPI {
+ #verifyOptions: JwtMachineVerifyOptions;
+
+ /**
+ * @param verifyOptions - JWT verification options (secretKey, apiUrl, etc.).
+ * Passed explicitly because BuildRequestOptions are captured inside the buildRequest closure
+ * and are not accessible from the RequestFunction itself.
+ */
+ constructor(request: RequestFunction, verifyOptions: JwtMachineVerifyOptions = {}) {
+ super(request);
+ this.#verifyOptions = verifyOptions;
+ }
+
  #createRequestOptions(options: ClerkBackendApiRequestOptions, machineSecretKey?: string) {
  if (machineSecretKey) {
  return {
@@ -88,7 +116,7 @@ export class M2MTokenApi extends AbstractAPI {
  }
 
  async createToken(params?: CreateM2MTokenParams) {
- const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
+ const { claims = null, machineSecretKey, secondsUntilExpiration = null, tokenFormat = 'opaque' } = params || {};
 
  const requestOptions = this.#createRequestOptions(
  {
@@ -97,6 +125,7 @@ export class M2MTokenApi extends AbstractAPI {
  bodyParams: {
  secondsUntilExpiration,
  claims,
+ tokenFormat,
  },
  },
  machineSecretKey,
@@ -124,9 +153,35 @@ export class M2MTokenApi extends AbstractAPI {
  return this.request<M2MToken>(requestOptions);
  }
 
+ async #verifyJwtFormat(token: string): Promise<M2MToken> {
+ let decoded;
+ try {
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
+ }
+ decoded = data;
+ } catch (e) {
+ throw new MachineTokenVerificationError({
+ code: MachineTokenVerificationErrorCode.TokenInvalid,
+ message: (e as Error).message,
+ });
+ }
+
+ const result = await verifyM2MJwt(token, decoded, this.#verifyOptions);
+ if (result.errors) {
+ throw result.errors[0];
+ }
+ return result.data;
+ }
+
  async verify(params: VerifyM2MTokenParams) {
  const { token, machineSecretKey } = params;
 
+ if (isM2MJwt(token)) {
+ return this.#verifyJwtFormat(token);
+ }
+
  const requestOptions = this.#createRequestOptions(
  {
  method: 'POST',

.changeset/clever-ways-raise.md

@@ -0,0 +1,2 @@
+---
+---

integration/tests/machine-auth/m2m.test.ts

@@ -42,10 +42,9 @@ test.describe('machine-to-machine auth @machine', () => {
 
  app.get('/api/protected', async (req, res) => {
  const token = req.get('Authorization')?.split(' ')[1];
-
  try {
  const m2mToken = await clerkClient.m2m.verify({ token });
- res.send('Protected response ' + m2mToken.id);
+ res.send('Protected response ' + m2mToken.subject);
  } catch {
  res.status(401).send('Unauthorized');
  }
@@ -150,7 +149,7 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res.status()).toBe(200);
- expect(await res.text()).toBe('Protected response ' + emailServerM2MToken.id);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
 
  // Analytics server can access primary API server after adding scope
  await u.services.clerk.machines.createScope(analyticsServer.id, primaryApiServer.id);
@@ -165,9 +164,30 @@ test.describe('machine-to-machine auth @machine', () => {
  },
  });
  expect(res2.status()).toBe(200);
- expect(await res2.text()).toBe('Protected response ' + m2mToken.id);
+ expect(await res2.text()).toBe('Protected response ' + analyticsServer.id);
  await u.services.clerk.m2m.revokeToken({
  m2mTokenId: m2mToken.id,
  });
  });
+
+ test('verifies JWT format M2M token via local verification', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+
+ const client = createClerkClient({
+ secretKey: instanceKeys.get('with-api-keys').sk,
+ });
+ const jwtToken = await client.m2m.createToken({
+ machineSecretKey: emailServer.secretKey,
+ secondsUntilExpiration: 60 * 30,
+ tokenFormat: 'jwt',
+ });
+
+ const res = await u.page.request.get(app.serverUrl + '/api/protected', {
+ headers: { Authorization: `Bearer ${jwtToken.token}` },
+ });
+ expect(res.status()).toBe(200);
+ expect(await res.text()).toBe('Protected response ' + emailServer.id);
+ // JWT-format tokens are self-contained and not stored in BAPI, so revocation
+ // is not applicable — they expire naturally via the exp claim.
+ });
 });

packages/backend/src/__tests__/exports.test.ts

@@ -49,11 +49,9 @@ describe('subpath /internal exports', () => {
  "decorateObjectWithResources",
  "getAuthObjectForAcceptedToken",
  "getAuthObjectFromJwt",
- "getMachineTokenType",
  "invalidTokenAuthObject",
  "isMachineToken",
  "isMachineTokenByPrefix",
- "isMachineTokenType",
  "isTokenTypeAccepted",
  "makeAuthObjectSerializable",
  "reverificationError",

packages/backend/src/api/__tests__/M2MTokenApi.test.ts

@@ -1,8 +1,12 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { mockJwks, mockJwtPayload, mockM2MJwtPayload, signingJwks } from '../../fixtures';
+import { signJwt } from '../../jwt/signJwt';
 import { server, validateHeaders } from '../../mock-server';
+import { M2MTokenApi } from '../endpoints/M2MTokenApi';
 import { createBackendApiClient } from '../factory';
+import { buildRequest } from '../request';
 
 describe('M2MToken', () => {
  const m2mId = 'mt_1xxxxxxxxxxxxx';
@@ -110,6 +114,130 @@ describe('M2MToken', () => {
  'The provided Machine Secret Key is invalid. Make sure that your Machine Secret Key is correct.',
  );
  });
+
+ it('creates a jwt format m2m token', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ return HttpResponse.json({
+ ...mockM2MToken,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJpYXQiOjE3NTM3NDMzMTYsImV4cCI6MTc1Mzc0NjkxNn0.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ });
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates a jwt m2m token with custom claims and scopes', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ const customClaims = {
+ role: 'service',
+ tier: 'gold',
+ };
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('jwt');
+ expect(body.claims).toEqual(customClaims);
+ return HttpResponse.json({
+ ...mockM2MToken,
+ claims: customClaims,
+ token:
+ 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imluc194eHh4eCJ9.eyJqdGkiOiJtdF94eHh4eCIsInN1YiI6Im1jaF94eHh4eCIsImF1ZCI6WyJtY2hfMXh4eHh4IiwibWNoXzJ4eHh4eCJdLCJzY29wZXMiOiJtY2hfMXh4eHh4IG1jaF8yeHh4eHgiLCJyb2xlIjoic2VydmljZSIsInRpZXIiOiJnb2xkIiwiaWF0IjoxNzUzNzQzMzE2LCJleHAiOjE3NTM3NDY5MTZ9.signature',
+ });
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'jwt',
+ claims: customClaims,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/);
+ expect(response.claims).toEqual(customClaims);
+ expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
+ });
+
+ it('creates an opaque format m2m token when explicitly specified', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ tokenFormat: 'opaque',
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ expect(response.token).toMatch(/^mt_.+$/);
+ });
+
+ it('creates an opaque m2m token by default when tokenFormat is omitted', async () => {
+ const apiClient = createBackendApiClient({
+ apiUrl: 'https://api.clerk.test',
+ machineSecretKey: 'ak_xxxxx',
+ });
+
+ server.use(
+ http.post(
+ 'https://api.clerk.test/m2m_tokens',
+ validateHeaders(async ({ request }) => {
+ expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+ const body = (await request.json()) as Record<string, unknown>;
+ // tokenFormat defaults to 'opaque' when omitted
+ expect(body.token_format).toBe('opaque');
+ return HttpResponse.json(mockM2MToken);
+ }),
+ ),
+ );
+
+ const response = await apiClient.m2m.createToken({
+ secondsUntilExpiration: 3600,
+ });
+
+ expect(response.id).toBe(m2mId);
+ expect(response.token).toBe(m2mSecret);
+ });
  });
 
  describe('revoke', () => {
@@ -283,6 +411,72 @@ describe('M2MToken', () => {
  });
  });
 
+ async function createSignedM2MJwt(payload = mockM2MJwtPayload) {
+ const { data } = await signJwt(payload, signingJwks, {
+ algorithm: 'RS256',
+ header: { typ: 'JWT', kid: 'ins_2GIoQhbUpy0hX7B2cVkuTMinXoD' },
+ });
+ return data!;
+ }
+
+ describe('verify — JWT format', () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date(mockJwtPayload.iat * 1000));
+ });
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('verifies a JWT M2M token using secretKey (JWKS lookup)', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json(mockJwks)),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ const result = await m2mApi.verify({ token: jwtToken });
+
+ expect(result.id).toBe('mt_2xKa9Bgv7NxMRDFyQw8LpZ3cTmU1vHjE');
+ expect(result.subject).toBe('mch_2vYVtestTESTtestTESTtestTESTtest');
+ expect(result.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+ });
+
+ it('throws when JWT signature cannot be verified', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { secretKey: 'sk_test_xxxxx', apiUrl: 'https://api.clerk.test', skipJwksCache: true },
+ );
+
+ server.use(
+ http.get(
+ 'https://api.clerk.test/v1/jwks',
+ validateHeaders(() => HttpResponse.json({ keys: [] })),
+ ),
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow();
+ });
+
+ it('throws when no secretKey or jwtKey is provided', async () => {
+ const m2mApi = new M2MTokenApi(
+ buildRequest({ apiUrl: 'https://api.clerk.test', skipApiVersionInUrl: true, requireSecretKey: false }),
+ { apiUrl: 'https://api.clerk.test' },
+ );
+
+ const jwtToken = await createSignedM2MJwt();
+ await expect(m2mApi.verify({ token: jwtToken })).rejects.toThrow('Failed to resolve JWK during verification');
+ });
+ });
+
  describe('list', () => {
  const machineId = 'mch_1xxxxxxxxxxxxx';
  const mockM2MTokenList = {

packages/backend/src/api/endpoints/M2MTokenApi.ts

@@ -1,13 +1,25 @@
 import type { ClerkPaginationRequest } from '@clerk/shared/types';
 
+import { MachineTokenVerificationError, MachineTokenVerificationErrorCode } from '../../errors';
+import { decodeJwt } from '../../jwt/verifyJwt';
+import type { JwtMachineVerifyOptions } from '../../jwt/verifyMachineJwt';
+import { verifyM2MJwt } from '../../jwt/verifyMachineJwt';
+import { isM2MJwt } from '../../tokens/machine';
 import { joinPaths } from '../../util/path';
-import type { ClerkBackendApiRequestOptions } from '../request';
+import type { ClerkBackendApiRequestOptions, RequestFunction } from '../request';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+/**
+ * Format of the M2M token to create.
+ * - 'opaque': Opaque token with mt_ prefix
+ * - 'jwt': JWT signed with instance keys
+ */
+export type M2MTokenFormat = 'opaque' | 'jwt';
+
 type GetM2MTokenListParams = ClerkPaginationRequest<{
  /**
  * The machine ID to query machine-to-machine tokens by
@@ -39,6 +51,10 @@ type CreateM2MTokenParams = {
  */
  secondsUntilExpiration?: number | null;
  claims?: Record<string, unknown> | null;
+ /**
+ * @default 'opaque'
+ */
+ tokenFormat?: M2MTokenFormat;
 };
 
 type RevokeM2MTokenParams = {
@@ -65,6 +81,18 @@ type VerifyM2MTokenParams = {
 };
 
 export class M2MTokenApi extends AbstractAPI {
+ #verifyOptions: JwtMachineVerifyOptions;
+
+ /**
+ * @param verifyOptions - JWT verification options (secretKey, apiUrl, etc.).
+ * Passed explicitly because BuildRequestOptions are captured inside the buildRequest closure
+ * and are not accessible from the RequestFunction itself.
+ */
+ constructor(request: RequestFunction, verifyOptions: JwtMachineVerifyOptions = {}) {
+ super(request);
+ this.#verifyOptions = verifyOptions;
+ }
+
  #createRequestOptions(options: ClerkBackendApiRequestOptions, machineSecretKey?: string) {
  if (machineSecretKey) {
  return {
@@ -88,7 +116,7 @@ export class M2MTokenApi extends AbstractAPI {
  }
 
  async createToken(params?: CreateM2MTokenParams) {
- const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
+ const { claims = null, machineSecretKey, secondsUntilExpiration = null, tokenFormat = 'opaque' } = params || {};
 
  const requestOptions = this.#createRequestOptions(
  {
@@ -97,6 +125,7 @@ export class M2MTokenApi extends AbstractAPI {
  bodyParams: {
  secondsUntilExpiration,
  claims,
+ tokenFormat,
  },
  },
  machineSecretKey,
@@ -124,9 +153,35 @@ export class M2MTokenApi extends AbstractAPI {
  return this.request<M2MToken>(requestOptions);
  }
 
+ async #verifyJwtFormat(token: string): Promise<M2MToken> {
+ let decoded;
+ try {
+ const { data, errors } = decodeJwt(token);
+ if (errors) {
+ throw errors[0];
+ }
+ decoded = data;
+ } catch (e) {
+ throw new MachineTokenVerificationError({
+ code: MachineTokenVerificationErrorCode.TokenInvalid,
+ message: (e as Error).message,
+ });
+ }
+
+ const result = await verifyM2MJwt(token, decoded, this.#verifyOptions);
+ if (result.errors) {
+ throw result.errors[0];
+ }
+ return result.data;
+ }
+
  async verify(params: VerifyM2MTokenParams) {
  const { token, machineSecretKey } = params;
 
+ if (isM2MJwt(token)) {
+ return this.#verifyJwtFormat(token);
+ }
+
  const requestOptions = this.#createRequestOptions(
  {
  method: 'POST',