Add SDK reference for machines BAPI endpoint

docs/manifest.json

@@ -3360,6 +3360,59 @@
                             ]
                           ]
                         },
+                        {
+                          "title": "Machines",
+                          "collapse": true,
+                          "items": [
+                            [
+                              {
+                                "title": "`list()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/list"
+                              },
+                              {
+                                "title": "`create()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/create"
+                              },
+                              {
+                                "title": "`get()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/get"
+                              },
+                              {
+                                "title": "`update()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/update"
+                              },
+                              {
+                                "title": "`delete()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/delete"
+                              },
+                              {
+                                "title": "`getSecretKey()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/get-secret-key"
+                              },
+                              {
+                                "title": "`rotateSecretKey()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/rotate-secret-key"
+                              },
+                              {
+                                "title": "`createScope()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/create-scope"
+                              },
+                              {
+                                "title": "`deleteScope()`",
+                                "wrap": false,
+                                "href": "/docs/references/backend/machines/delete-scope"
+                              }
+                            ]
+                          ]
+                        },
                         {
                           "title": "M2M Tokens",
                           "collapse": true,

docs/references/backend/machines/create-scope.mdx

@@ -0,0 +1,42 @@
+---
+title: '`createScope()`'
+description: Use Clerk's Backend SDK to create a machine scope.
+sdk: js-backend
+---
+
+Creates a new machine scope, allowing the specified machine to access another machine.
+
+```ts
+function createScope(machineId: string, toMachineId: string): Promise<MachineScope>
+```
+
+## Parameters
+
+<Properties>
+  - `machineId`
+  - `string`
+
+  The ID of the machine that will have access to the target machine.
+
+  ---
+
+  - `toMachineId`
+  - `string`
+
+  The ID of the machine that will be accessible by the source machine.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```ts
+const machineId = 'mch_123'
+const toMachineId = 'mch_456'
+
+const response = await clerkClient.machines.createScope(machineId, toMachineId)
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `POST/machines/{machine_id}/scopes`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/post/machines/%7Bmachine_id%7D/scopes){{ target: '_blank' }} for more information.

docs/references/backend/machines/create.mdx

@@ -0,0 +1,60 @@
+---
+title: '`create()`'
+description: Use Clerk's Backend SDK to create a machine.
+sdk: js-backend
+---
+
+Creates a new machine.
+
+```ts
+function create(params: CreateMachineParams): Promise<Machine>
+```
+
+## `CreateMachineParams`
+
+<Properties>
+  - `name`
+  - `string`
+
+  The name of the machine.
+
+  ---
+
+  - `scopedMachines?`
+  - `string[]`
+
+  Array of machine IDs that this machine will have access to.
+
+  ---
+
+  - `defaultTokenTtl?`
+  - `number`
+
+  The default time-to-live (TTL) in seconds for tokens created by this machine.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+### Basic machine creation
+
+```ts
+const response = await clerkClient.machines.create({
+  name: 'Email Server',
+})
+```
+
+### Machine with scoped access
+
+```ts
+const response = await clerkClient.machines.create({
+  name: 'API Gateway',
+  scopedMachines: ['mch_123', 'mch_456'],
+  defaultTokenTtl: 3600,
+})
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `POST/machines`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/post/machines){{ target: '_blank' }} for more information.

docs/references/backend/machines/delete-scope.mdx

@@ -0,0 +1,42 @@
+---
+title: '`deleteScope()`'
+description: Use Clerk's Backend SDK to delete a machine scope.
+sdk: js-backend
+---
+
+Deletes a machine scope, removing access between two machines.
+
+```ts
+function deleteScope(machineId: string, otherMachineId: string): Promise<MachineScope>
+```
+
+## Parameters
+
+<Properties>
+  - `machineId`
+  - `string`
+
+  The ID of the machine that currently has access to the target machine.
+
+  ---
+
+  - `otherMachineId`
+  - `string`
+
+  The ID of the machine that will no longer be accessible by the source machine.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```ts
+const machineId = 'mch_123'
+const otherMachineId = 'mch_456'
+
+const response = await clerkClient.machines.deleteScope(machineId, otherMachineId)
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `DELETE/machines/{machine_id}/scopes/{other_machine_id}`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/delete/machines/%7Bmachine_id%7D/scopes/%7Bother_machine_id%7D){{ target: '_blank' }} for more information.

docs/references/backend/machines/delete.mdx

@@ -0,0 +1,34 @@
+---
+title: '`delete()`'
+description: Use Clerk's Backend SDK to delete a machine.
+sdk: js-backend
+---
+
+Deletes a machine by its ID.
+
+```ts {{ prettier: false }}
+function delete(machineId: string): Promise<Machine>
+```
+
+## Parameters
+
+<Properties>
+  - `machineId`
+  - `string`
+
+  The ID of the machine to delete.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```ts
+const machineId = 'mch_123'
+
+const response = await clerkClient.machines.delete(machineId)
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `DELETE/machines/{machine_id}`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/delete/machines/%7Bmachine_id%7D){{ target: '_blank' }} for more information.

docs/references/backend/machines/get-secret-key.mdx

@@ -0,0 +1,34 @@
+---
+title: '`getSecretKey()`'
+description: Use Clerk's Backend SDK to retrieve a machine secret key.
+sdk: js-backend
+---
+
+Retrieves a machine secret key by its ID.
+
+```ts
+function getSecretKey(machineId: string): Promise<MachineSecretKey>
+```
+
+## Parameters
+
+<Properties>
+  - `machineId`
+  - `string`
+
+  The ID of the machine for which to retrieve the secret key.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```ts
+const machineId = 'mch_123'
+
+const response = await clerkClient.machines.getSecretKey(machineId)
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `GET/machines/{machine_id}/secret_key`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/get/machines/%7Bmachine_id%7D/secret_key){{ target: '_blank' }} for more information.

docs/references/backend/machines/get.mdx

@@ -0,0 +1,34 @@
+---
+title: '`get()`'
+description: Use Clerk's Backend SDK to retrieve a machine.
+sdk: js-backend
+---
+
+Retrieves a machine by its ID.
+
+```ts
+function get(machineId: string): Promise<Machine>
+```
+
+## Parameters
+
+<Properties>
+  - `machineId`
+  - `string`
+
+  The ID of the machine to retrieve.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```ts
+const machineId = 'mch_123'
+
+const response = await clerkClient.machines.get(machineId)
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `GET/machines/{machine_id}`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/get/machines/%7Bmachine_id%7D){{ target: '_blank' }} for more information.

docs/references/backend/machines/list.mdx

@@ -0,0 +1,77 @@
+---
+title: '`list()`'
+description: Use Clerk's Backend SDK to get a list of machines for your application.
+sdk: js-backend
+---
+
+Retrieves a list of machines for your application. Returns a [`PaginatedResourceResponse`](/docs/references/backend/types/paginated-resource-response) object with a `data` property that contains an array of Machine objects, and a `totalCount` property that indicates the total number of machines for the application. Results are sorted by descending creation date by default.
+
+```ts
+function list(params: GetMachineListParams = {}): Promise<PaginatedResourceResponse<Machine[]>>
+```
+
+## Parameters
+
+<Properties>
+  - `limit?`
+  - `number`
+
+  The number of results to return. Must be an integer greater than zero and less than 501. Can be used for paginating the results together with `offset`. Defaults to `10`.
+
+  ---
+
+  - `offset?`
+  - `number`
+
+  Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`. Defaults to `0`.
+
+  ---
+
+  - `orderBy?`
+  - `'name' | 'created_at'`
+
+  Return machines in a particular order. Prefix with a `-` to reverse the order. Prefix with a `+` to list in ascending order. Defaults to `'+created_at'`.
+
+  ---
+
+  - `query?`
+  - `string`
+
+  Filters machines with ID or name that match the given query.
+</Properties>
+
+## Examples
+
+<Include src="_partials/backend/usage" />
+
+### Basic
+
+```tsx
+const response = await clerkClient.machines.list()
+```
+
+### Limit the number of results
+
+Retrieves list of machines that is filtered by the number of results.
+
+```tsx
+const { data, totalCount } = await clerkClient.machines.list({
+  // returns the first 10 results
+  limit: 10,
+})
+```
+
+### Skip results
+
+Retrieves list of machines that is filtered by the number of results to skip.
+
+```tsx
+const { data, totalCount } = await clerkClient.machines.list({
+  // skips the first 10 results
+  offset: 10,
+})
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `GET/machines`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/get/machines){{ target: '_blank' }} for more information.