chore(backend): Add M2M token list method

.changeset/shiny-apples-travel.md

@@ -0,0 +1,29 @@
+---
+"@clerk/backend": minor
+---
+
+Add `list()` method to M2M tokens API to retrieve a list of machine-to-machine tokens for a given machine.
+
+```ts
+// Retrieve M2M tokens for a specific machine
+const response = await clerkClient.m2m.list({
+  subject: 'mch_1xxxxxxxxxxxxx',
+});
+
+console.log(response.data); // M2MToken[]
+console.log(response.totalCount); // number
+```
+
+Filter by revoked or expired tokens:
+
+```ts
+const revokedTokens = await clerkClient.m2m.list({
+  subject: 'mch_1xxxxxxxxxxxxx',
+  revoked: true,
+});
+
+const expiredTokens = await clerkClient.m2m.list({
+  subject: 'mch_1xxxxxxxxxxxxx',
+  expired: true,
+});
+```

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

@@ -5,14 +5,14 @@ import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
 
 describe('M2MToken', () => {
-  const m2mId = 'mt_xxxxx';
-  const m2mSecret = 'mt_secret_xxxxx';
+  const m2mId = 'mt_1xxxxxxxxxxxxx';
+  const m2mSecret = 'mt_secret_1xxxxxxxxxxxxx';
 
   const mockM2MToken = {
     object: 'machine_to_machine_token',
     id: m2mId,
-    subject: 'mch_xxxxx',
-    scopes: ['mch_1xxxxx', 'mch_2xxxxx'],
+    subject: 'mch_1xxxxxxxxxxxxx',
+    scopes: ['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx'],
     claims: { foo: 'bar' },
     token: m2mSecret,
     revoked: false,
@@ -46,7 +46,7 @@ describe('M2MToken', () => {
 
       expect(response.id).toBe(m2mId);
       expect(response.token).toBe(m2mSecret);
-      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
       expect(response.claims).toEqual({ foo: 'bar' });
     });
 
@@ -72,7 +72,7 @@ describe('M2MToken', () => {
 
       expect(response.id).toBe(m2mId);
       expect(response.token).toBe(m2mSecret);
-      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
       expect(response.claims).toEqual({ foo: 'bar' });
     });
 
@@ -116,8 +116,8 @@ describe('M2MToken', () => {
     const mockRevokedM2MToken = {
       object: 'machine_to_machine_token',
       id: m2mId,
-      subject: 'mch_xxxxx',
-      scopes: ['mch_1xxxxx', 'mch_2xxxxx'],
+      subject: 'mch_1xxxxxxxxxxxxx',
+      scopes: ['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx'],
       claims: { foo: 'bar' },
       revoked: true,
       revocation_reason: 'revoked by test',
@@ -151,7 +151,7 @@ describe('M2MToken', () => {
       expect(response.revoked).toBe(true);
       expect(response.token).toBeUndefined();
       expect(response.revocationReason).toBe('revoked by test');
-      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
       expect(response.claims).toEqual({ foo: 'bar' });
     });
 
@@ -229,7 +229,7 @@ describe('M2MToken', () => {
 
       expect(response.id).toBe(m2mId);
       expect(response.token).toBe(m2mSecret);
-      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
       expect(response.claims).toEqual({ foo: 'bar' });
     });
 
@@ -255,7 +255,7 @@ describe('M2MToken', () => {
 
       expect(response.id).toBe(m2mId);
       expect(response.token).toBe(m2mSecret);
-      expect(response.scopes).toEqual(['mch_1xxxxx', 'mch_2xxxxx']);
+      expect(response.scopes).toEqual(['mch_1xxxxxxxxxxxxx', 'mch_2xxxxxxxxxxxxx']);
       expect(response.claims).toEqual({ foo: 'bar' });
     });
 
@@ -282,4 +282,187 @@ describe('M2MToken', () => {
       expect(errResponse.status).toBe(401);
     });
   });
+
+  describe('list', () => {
+    const machineId = 'mch_1xxxxxxxxxxxxx';
+    const mockM2MTokenList = {
+      m2m_tokens: [
+        {
+          ...mockM2MToken,
+          id: 'mt_1xxxxxxxxxxxxx',
+        },
+        {
+          ...mockM2MToken,
+          id: 'mt_2xxxxxxxxxxxxx',
+          revoked: true,
+        },
+      ],
+      total_count: 2,
+    };
+
+    it('lists m2m tokens with machine secret key', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+        machineSecretKey: 'ak_xxxxx',
+      });
+
+      server.use(
+        http.get(
+          'https://api.clerk.test/m2m_tokens',
+          validateHeaders(({ request }) => {
+            expect(request.headers.get('Authorization')).toBe('Bearer ak_xxxxx');
+            const url = new URL(request.url);
+            expect(url.searchParams.get('subject')).toBe(machineId);
+            expect(url.searchParams.get('limit')).toBe('10');
+            return HttpResponse.json(mockM2MTokenList);
+          }),
+        ),
+      );
+
+      const response = await apiClient.m2m.list({
+        subject: machineId,
+        limit: 10,
+      });
+
+      expect(response.data).toHaveLength(2);
+      expect(response.data[0].id).toBe('mt_1xxxxxxxxxxxxx');
+      expect(response.data[1].id).toBe('mt_2xxxxxxxxxxxxx');
+      expect(response.totalCount).toBe(2);
+    });
+
+    it('lists m2m tokens with instance secret key', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'sk_xxxxx',
+      });
+
+      server.use(
+        http.get(
+          'https://api.clerk.test/m2m_tokens',
+          validateHeaders(({ request }) => {
+            expect(request.headers.get('Authorization')).toBe('Bearer sk_xxxxx');
+            return HttpResponse.json(mockM2MTokenList);
+          }),
+        ),
+      );
+
+      const response = await apiClient.m2m.list({
+        subject: machineId,
+      });
+
+      expect(response.data).toHaveLength(2);
+      expect(response.totalCount).toBe(2);
+    });
+
+    it('lists m2m tokens with revoked filter', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'sk_xxxxx',
+      });
+
+      server.use(
+        http.get(
+          'https://api.clerk.test/m2m_tokens',
+          validateHeaders(({ request }) => {
+            const url = new URL(request.url);
+            expect(url.searchParams.get('revoked')).toBe('true');
+            return HttpResponse.json(mockM2MTokenList);
+          }),
+        ),
+      );
+
+      const response = await apiClient.m2m.list({
+        subject: machineId,
+        revoked: true,
+      });
+
+      expect(response.data).toHaveLength(2);
+    });
+
+    it('lists m2m tokens with expired filter', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'sk_xxxxx',
+      });
+
+      server.use(
+        http.get(
+          'https://api.clerk.test/m2m_tokens',
+          validateHeaders(({ request }) => {
+            const url = new URL(request.url);
+            expect(url.searchParams.get('expired')).toBe('true');
+            return HttpResponse.json(mockM2MTokenList);
+          }),
+        ),
+      );
+
+      const response = await apiClient.m2m.list({
+        subject: machineId,
+        expired: true,
+      });
+
+      expect(response.data).toHaveLength(2);
+    });
+
+    it('lists m2m tokens with pagination', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'sk_xxxxx',
+      });
+
+      server.use(
+        http.get(
+          'https://api.clerk.test/m2m_tokens',
+          validateHeaders(({ request }) => {
+            const url = new URL(request.url);
+            expect(url.searchParams.get('limit')).toBe('5');
+            expect(url.searchParams.get('offset')).toBe('10');
+            return HttpResponse.json(mockM2MTokenList);
+          }),
+        ),
+      );
+
+      const response = await apiClient.m2m.list({
+        subject: machineId,
+        limit: 5,
+        offset: 10,
+      });
+
+      expect(response.data).toHaveLength(2);
+      expect(response.totalCount).toBe(2);
+    });
+
+    it('requires a machine secret or instance secret to list m2m tokens', async () => {
+      const apiClient = createBackendApiClient({
+        apiUrl: 'https://api.clerk.test',
+      });
+
+      server.use(
+        http.get(
+          'https://api.clerk.test/m2m_tokens',
+          validateHeaders(() => {
+            return HttpResponse.json(
+              {
+                errors: [
+                  {
+                    message: 'Unauthorized',
+                    code: 'unauthorized',
+                  },
+                ],
+              },
+              { status: 401 },
+            );
+          }),
+        ),
+      );
+
+      const errResponse = await apiClient.m2m
+        .list({
+          subject: machineId,
+        })
+        .catch(err => err);
+
+      expect(errResponse.status).toBe(401);
+    });
+  });
 });

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

@@ -1,11 +1,33 @@
+import type { ClerkPaginationRequest } from '@clerk/shared/types';
+
 import { joinPaths } from '../../util/path';
 import { deprecated } from '../../util/shared';
 import type { ClerkBackendApiRequestOptions } from '../request';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import type { M2MToken } from '../resources/M2MToken';
 import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/m2m_tokens';
 
+type GetM2MTokenListParams = ClerkPaginationRequest<{
+  /**
+   * The machine ID to query machine-to-machine tokens by
+   */
+  subject: string;
+  /**
+   * Whether to include revoked machine-to-machine tokens.
+   *
+   * @default false
+   */
+  revoked?: boolean;
+  /**
+   * Whether to include expired machine-to-machine tokens.
+   *
+   * @default false
+   */
+  expired?: boolean;
+}>;
+
 type CreateM2MTokenParams = {
   /**
    * Custom machine secret key for authentication.
@@ -58,6 +80,14 @@ export class M2MTokenApi extends AbstractAPI {
     return options;
   }
 
+  async list(queryParams: GetM2MTokenListParams) {
+    return this.request<PaginatedResourceResponse<M2MToken[]>>({
+      method: 'GET',
+      path: basePath,
+      queryParams,
+    });
+  }
+
   async createToken(params?: CreateM2MTokenParams) {
     const { claims = null, machineSecretKey, secondsUntilExpiration = null } = params || {};
 

packages/backend/src/api/resources/Deserializer.ts

@@ -77,6 +77,12 @@ export function deserialize<U = any>(payload: unknown): PaginatedResourceRespons
   if (Array.isArray(payload)) {
     const data = payload.map(item => jsonToObject(item)) as U;
     return { data };
+  } else if (isM2MTokenResponse(payload)) {
+    // Handle M2M token list responses with m2m_tokens property
+    data = payload.m2m_tokens.map(item => jsonToObject(item)) as U;
+    totalCount = payload.total_count;
+
+    return { data, totalCount };
   } else if (isPaginated(payload)) {
     data = payload.data.map(item => jsonToObject(item)) as U;
     totalCount = payload.total_count;
@@ -95,6 +101,27 @@ function isPaginated(payload: unknown): payload is PaginatedResponseJSON {
   return Array.isArray(payload.data) && payload.data !== undefined;
 }
 
+/**
+ * Detects M2M token list responses from the Backend API.
+ *
+ * The Clerk Backend API returns M2M token lists with `m2m_tokens` and `total_count` properties.
+ * This function identifies those responses and normalizes them to the standard `data` and
+ * `totalCount` format for consistency with other paginated API methods across the SDK.
+ *
+ * This approach avoids making breaking changes to BAPI Proxy or supporting both response
+ * formats. Once BAPI Proxy is updated to return the standard `data` property format,
+ * this function can be safely removed.
+ *
+ * @see https://clerk.com/docs/reference/backend-api/tag/m2m-tokens/get/m2m_tokens
+ */
+function isM2MTokenResponse(payload: unknown): payload is { m2m_tokens: unknown[]; total_count: number } {
+  if (!payload || typeof payload !== 'object' || !('m2m_tokens' in payload)) {
+    return false;
+  }
+
+  return Array.isArray(payload.m2m_tokens);
+}
+
 function getCount(item: PaginatedResponseJSON) {
   return item.total_count;
 }