Add M2M tokens list method reference #3165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

wobsoriano merged 12 commits into main from rob/m2m-list-method

Mar 4, 2026

docs/guides/development/machine-auth/m2m-tokens.mdx

-Original file line number
+Diff line change
@@ Expand Up @@
     - `secondsUntilExpiration` - The number of seconds until the token will expire. By default, the token will not expire.
     - `claims` - A JavaScript object that can be used to store additional information about the token.
+    ## Listing M2M tokens for a given machine
+    To retrieve a list of M2M tokens for a given machine, call the [`list()`](/docs/reference/backend/m2m-tokens/list) method:
+    ```ts
+    const machineId = 'mt_123'
+    // The subject parameter can be used to filter M2M tokens by machine ID. In this example, only tokens associated with the machine with the ID of 'mt_123' will be returned.
+    const m2mTokens = await clerkClient.m2m.list({
+      subject: machineId,
+    })
+    ```
     ## Verifying M2M tokens
     Imagine a request was made from **Machine A** to **Machine B**, and Machine B received it successfully. The next step is to verify that the token is valid and that the request is coming from a valid machine. To do so, you can use the [`verify()`](/docs/reference/backend/m2m-tokens/verify) method:
@@ Expand Down @@

docs/manifest.json

-Original file line number
+Diff line change
@@ Expand Up / @@ -2992,6 +2992,11 @@ @@
                               "title": "M2M Tokens",
                               "items": [
                                 [
+                                  {
+                                    "title": "`list()`",
+                                    "wrap": false,
+                                    "href": "/docs/reference/backend/m2m-tokens/list"
+                                  },
                                   {
                                     "title": "`createToken()`",
                                     "wrap": false,
@@ Expand Down @@

docs/reference/backend/m2m-tokens/list.mdx

-Original file line number
+Diff line change
@@ -0,0 +1,103 @@
+    ---
+    title: '`list()`'
+    description: Use Clerk's JS Backend SDK to get a list of M2M tokens for your a given machine.
+    sdk: js-backend
+    ---
+    Retrieves a list of M2M tokens for a given machine. Returns a [`PaginatedResourceResponse`](/docs/reference/backend/types/paginated-resource-response) object with a `data` property that contains an array of [M2M token](/docs/guides/development/machine-auth/m2m-tokens) objects, and a `totalCount` property that indicates the total number of M2M tokens in the system. This endpoint can be authenticated by either a Machine Secret Key or by a Clerk [Secret Key](!secret-key).
+    - When fetching M2M tokens with a Machine Secret Key, only tokens associated with the authenticated machine can be retrieved.
+    - When fetching M2M tokens with a Clerk Secret Key, tokens for any machine in the instance can be retrieved.
+    > [!NOTE]
+    > JWT tokens are not stored by Clerk, so they cannot be fetched via the list endpoint.
+    ```ts
+    function list(queryParams: GetM2MTokenListParams): Promise<PaginatedResourceResponse<M2MToken[]>>
+    ```
+    ## `GetM2MTokenListParams`
+    <Properties>
+      - `subject`
+      - `string`
+      The machine ID to query M2M tokens by.
+      ---
+      - `machineSecretKey?`
+      - `string`
+      Custom machine secret key for authentication. If not provided, the SDK will use the value from the environment variable.
+      ---
+      - `revoked?`
+      - `boolean`
+      Whether to include revoked M2M tokens. Defaults to `false`.
+      ---
+      - `expired?`
+      - `boolean`
+      Whether to include expired M2M tokens. Defaults to `false`.
+      ---
+      - `limit?`
+      - `number`
+      The maximum number of M2M tokens to return. Defaults to `10`.
+      ---
+      - `offset?`
+      - `number`
+      The number of M2M tokens to skip before returning results. Defaults to `0`.
+    </Properties>
+    ## Example
+    <Include src="_partials/backend/usage" />
+    ### List M2M tokens for a machine
+    ```tsx
+    const machineId = 'mt_123'
+    const m2mTokens = await clerkClient.m2m.list({
+      subject: machineId,
+    })
+    ```
+    ### List M2M tokens for a machine, including revoked and expired ones
+    ```tsx
+    const machineId = 'mt_123'
+    const m2mTokens = await clerkClient.m2m.list({
+      subject: machineId,
+      revoked: true,
+      expired: true,
+    })
+    ```
+    ### List M2M tokens for a machine with pagination
+    ```tsx
+    const machineId = 'mt_123'
+    const m2mTokens = await clerkClient.m2m.list({
+      subject: machineId,
+      limit: 20,
+      offset: 0,
+    })
+    ```
+    ## Backend API (BAPI) endpoint
+    This method in the SDK is a wrapper around the BAPI endpoint `GET/m2m_tokens`. See the [BAPI reference](/docs/reference/backend-api/tag/m2m-tokens/get/m2m_tokens){{ target: '_blank' }} for more information.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add M2M tokens list method reference #3165

Uh oh!

Diff view

Diff view

There are no files selected for viewing