# list()

Retrieves a list of M2M tokens for a given machine. Returns a [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response.md) object with a `data` property that contains an array of [M2M token](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens.md) 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.

- 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.

> JWT tokens are not stored by Clerk, so they cannot be fetched via the **list** endpoint (`clerkClient.m2m.list()`). The list endpoint will only return opaque tokens. Additionally, since JWT verification happens client-side, Clerk cannot track `last_used_at` for JWT tokens.

```ts
function list(queryParams: GetM2MTokenListParams): Promise<PaginatedResourceResponse<M2MToken[]>>
```

## `GetM2MTokenListParams`

| Name              | Type    | Description                                                                                                              |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| 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.                                                |

## Example

> Using `clerkClient` varies based on the SDK you're using. Refer to the [overview](https://clerk.com/docs/reference/backend/overview.md) for usage details, including guidance on [how to access the `userId` and other properties](https://clerk.com/docs/reference/backend/overview.md#example-get-the-user-id-and-other-properties).

### 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](https://clerk.com/docs/reference/backend-api/tag/m2m-tokens/GET/m2m_tokens){{ target: '_blank' }} for more information.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)