From 051417a0d73259251e85d532ff27670c1ad09432 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Thu, 11 Sep 2025 22:53:22 -0700
Subject: [PATCH 01/14] Add initial machines BAPI docs

---
 docs/manifest.json                            | 48 +++++++++++++++++++
 .../backend/machines/create-scope.mdx         |  7 +++
 docs/references/backend/machines/create.mdx   | 48 +++++++++++++++++++
 .../backend/machines/delete-scope.mdx         |  7 +++
 docs/references/backend/machines/delete.mdx   |  7 +++
 .../backend/machines/get-secret-key.mdx       |  7 +++
 docs/references/backend/machines/get.mdx      |  7 +++
 docs/references/backend/machines/list.mdx     |  7 +++
 docs/references/backend/machines/update.mdx   |  7 +++
 9 files changed, 145 insertions(+)
 create mode 100644 docs/references/backend/machines/create-scope.mdx
 create mode 100644 docs/references/backend/machines/create.mdx
 create mode 100644 docs/references/backend/machines/delete-scope.mdx
 create mode 100644 docs/references/backend/machines/delete.mdx
 create mode 100644 docs/references/backend/machines/get-secret-key.mdx
 create mode 100644 docs/references/backend/machines/get.mdx
 create mode 100644 docs/references/backend/machines/list.mdx
 create mode 100644 docs/references/backend/machines/update.mdx

diff --git a/docs/manifest.json b/docs/manifest.json
index 50f70db314..e67f266a3c 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -3360,6 +3360,54 @@
                             ]
                           ]
                         },
+                        {
+                          "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": "`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,
diff --git a/docs/references/backend/machines/create-scope.mdx b/docs/references/backend/machines/create-scope.mdx
new file mode 100644
index 0000000000..085119d465
--- /dev/null
+++ b/docs/references/backend/machines/create-scope.mdx
@@ -0,0 +1,7 @@
+---
+title: '`createScope()`'
+description: Use Clerk's Backend SDK to create a machine scope.
+sdk: js-backend
+---
+
+Creates a new machine scope.
diff --git a/docs/references/backend/machines/create.mdx b/docs/references/backend/machines/create.mdx
new file mode 100644
index 0000000000..e771664332
--- /dev/null
+++ b/docs/references/backend/machines/create.mdx
@@ -0,0 +1,48 @@
+---
+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" />
+
+```ts
+const response = await clerkClient.machines.create({
+  name: 'Email Server'
+})
+```
+
+## 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.
diff --git a/docs/references/backend/machines/delete-scope.mdx b/docs/references/backend/machines/delete-scope.mdx
new file mode 100644
index 0000000000..a10f0b3428
--- /dev/null
+++ b/docs/references/backend/machines/delete-scope.mdx
@@ -0,0 +1,7 @@
+---
+title: '`deleteScope()`'
+description: Use Clerk's Backend SDK to delete a machine scope.
+sdk: js-backend
+---
+
+Deletes a machine scope.
diff --git a/docs/references/backend/machines/delete.mdx b/docs/references/backend/machines/delete.mdx
new file mode 100644
index 0000000000..7375bb203e
--- /dev/null
+++ b/docs/references/backend/machines/delete.mdx
@@ -0,0 +1,7 @@
+---
+title: '`delete()`'
+description: Use Clerk's Backend SDK to delete a machine.
+sdk: js-backend
+---
+
+Deletes a machine.
diff --git a/docs/references/backend/machines/get-secret-key.mdx b/docs/references/backend/machines/get-secret-key.mdx
new file mode 100644
index 0000000000..58d24e0c10
--- /dev/null
+++ b/docs/references/backend/machines/get-secret-key.mdx
@@ -0,0 +1,7 @@
+---
+title: '`getSecretKey()`'
+description: Use Clerk's Backend SDK to retrieve a machine secret key.
+sdk: js-backend
+---
+
+Retrieves a machine secret key.
diff --git a/docs/references/backend/machines/get.mdx b/docs/references/backend/machines/get.mdx
new file mode 100644
index 0000000000..d46efb78aa
--- /dev/null
+++ b/docs/references/backend/machines/get.mdx
@@ -0,0 +1,7 @@
+---
+title: '`get()`'
+description: Use Clerk's Backend SDK to retrieve a single machine.
+sdk: js-backend
+---
+
+Retrieves a single machine.
diff --git a/docs/references/backend/machines/list.mdx b/docs/references/backend/machines/list.mdx
new file mode 100644
index 0000000000..3647d17558
--- /dev/null
+++ b/docs/references/backend/machines/list.mdx
@@ -0,0 +1,7 @@
+---
+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, sorted by descending creation date.
diff --git a/docs/references/backend/machines/update.mdx b/docs/references/backend/machines/update.mdx
new file mode 100644
index 0000000000..06bae13df7
--- /dev/null
+++ b/docs/references/backend/machines/update.mdx
@@ -0,0 +1,7 @@
+---
+title: '`delete()`'
+description: Use Clerk's Backend SDK to update a machine.
+sdk: js-backend
+---
+
+Updates a machine.

From 54150ed2d13aac15934aaf5085b95ec0d5b5c949 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Fri, 12 Sep 2025 13:23:52 -0700
Subject: [PATCH 02/14] Add more examples

---
 docs/manifest.json                            |  5 +++
 .../backend/machines/create-scope.mdx         |  6 +++-
 docs/references/backend/machines/delete.mdx   | 29 +++++++++++++++-
 .../backend/machines/get-secret-key.mdx       | 29 +++++++++++++++-
 docs/references/backend/machines/get.mdx      | 31 +++++++++++++++--
 .../backend/machines/rotate-secret-key.mdx    | 34 +++++++++++++++++++
 6 files changed, 129 insertions(+), 5 deletions(-)
 create mode 100644 docs/references/backend/machines/rotate-secret-key.mdx

diff --git a/docs/manifest.json b/docs/manifest.json
index e67f266a3c..0c1d6cea9e 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -3395,6 +3395,11 @@
                                 "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,
diff --git a/docs/references/backend/machines/create-scope.mdx b/docs/references/backend/machines/create-scope.mdx
index 085119d465..ffa323e8a4 100644
--- a/docs/references/backend/machines/create-scope.mdx
+++ b/docs/references/backend/machines/create-scope.mdx
@@ -4,4 +4,8 @@ description: Use Clerk's Backend SDK to create a machine scope.
 sdk: js-backend
 ---
 
-Creates a new machine scope.
+Creates a new machine scope, allowing the specified machine to access another machine.
+
+```ts
+function create(machineId: string, toMachineId: string): Promise<MachineScope>
+```
diff --git a/docs/references/backend/machines/delete.mdx b/docs/references/backend/machines/delete.mdx
index 7375bb203e..d7afe7e47f 100644
--- a/docs/references/backend/machines/delete.mdx
+++ b/docs/references/backend/machines/delete.mdx
@@ -4,4 +4,31 @@ description: Use Clerk's Backend SDK to delete a machine.
 sdk: js-backend
 ---
 
-Deletes a machine.
+Deletes a machine by its ID.
+
+```ts
+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.
diff --git a/docs/references/backend/machines/get-secret-key.mdx b/docs/references/backend/machines/get-secret-key.mdx
index 58d24e0c10..33c0065bd5 100644
--- a/docs/references/backend/machines/get-secret-key.mdx
+++ b/docs/references/backend/machines/get-secret-key.mdx
@@ -4,4 +4,31 @@ description: Use Clerk's Backend SDK to retrieve a machine secret key.
 sdk: js-backend
 ---
 
-Retrieves a machine secret key.
+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.
diff --git a/docs/references/backend/machines/get.mdx b/docs/references/backend/machines/get.mdx
index d46efb78aa..9f4a51f59f 100644
--- a/docs/references/backend/machines/get.mdx
+++ b/docs/references/backend/machines/get.mdx
@@ -1,7 +1,34 @@
 ---
 title: '`get()`'
-description: Use Clerk's Backend SDK to retrieve a single machine.
+description: Use Clerk's Backend SDK to retrieve a machine.
 sdk: js-backend
 ---
 
-Retrieves a single machine.
+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.
diff --git a/docs/references/backend/machines/rotate-secret-key.mdx b/docs/references/backend/machines/rotate-secret-key.mdx
new file mode 100644
index 0000000000..f4aa4221f3
--- /dev/null
+++ b/docs/references/backend/machines/rotate-secret-key.mdx
@@ -0,0 +1,34 @@
+---
+title: '`rotateSecretKey()`'
+description: Use Clerk's Backend SDK to rotate a machine's secret key.
+sdk: js-backend
+---
+
+Rotates the machine secret key for a given machine by its ID.
+
+```ts
+function rotateSecretKey(machineId: string): Promise<MachineSecretKey>
+```
+
+## Parameters
+
+<Properties>
+  - `machineId`
+  - `string`
+
+  The ID of the machine for which to rotate the secret key.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```ts
+const machineId = 'mch_123'
+
+const response = await clerkClient.machines.rotateSecretKey(machineId)
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `POST/machines/{machine_id}/secret_key/rotate`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/post/machines/%7Bmachine_id%7D/secret_key/rotate){{ target: '_blank' }} for more information.

From e693ef4f070b3f855b502bb6c5019efce7fd3a12 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Fri, 12 Sep 2025 15:55:59 -0700
Subject: [PATCH 03/14] add list, update methods

---
 docs/references/backend/machines/list.mdx   | 72 +++++++++++++++++++++
 docs/references/backend/machines/update.mdx | 47 +++++++++++++-
 2 files changed, 118 insertions(+), 1 deletion(-)

diff --git a/docs/references/backend/machines/list.mdx b/docs/references/backend/machines/list.mdx
index 3647d17558..8415093a2f 100644
--- a/docs/references/backend/machines/list.mdx
+++ b/docs/references/backend/machines/list.mdx
@@ -5,3 +5,75 @@ sdk: js-backend
 ---
 
 Retrieves a list of machines for your application, sorted by descending creation date.
+
+```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.
diff --git a/docs/references/backend/machines/update.mdx b/docs/references/backend/machines/update.mdx
index 06bae13df7..81be9ddf51 100644
--- a/docs/references/backend/machines/update.mdx
+++ b/docs/references/backend/machines/update.mdx
@@ -4,4 +4,49 @@ description: Use Clerk's Backend SDK to update a machine.
 sdk: js-backend
 ---
 
-Updates a machine.
+Updates a machine by its ID.
+
+```ts
+function update(params: UpdateMachineParams): Promise<Machine>
+```
+
+## Parameters
+
+<Properties>
+  - `machineId`
+  - `string`
+
+    The ID of the machine to update.
+
+    ---
+
+  - `name`
+  - `string`
+
+  The name of the machine.
+
+  ---
+
+  - `defaultTokenTtl?`
+  - `number`
+
+  The default time-to-live (TTL) in seconds for tokens created by this machine.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```ts
+const machineId = 'mch_123'
+
+const response = await clerkClient.machines.update({
+  machineId,
+  name: 'New Machine Name',
+  defaultTokenTtl: 3600
+})
+```
+
+## Backend API (BAPI) endpoint
+
+This method in the SDK is a wrapper around the BAPI endpoint `PATCH/machines/{machine_id}`. See the [BAPI reference](/docs/reference/backend-api/tag/machines/patch/machines/%7Bmachine_id%7D){{ target: '_blank' }} for more information.

From 3299e3b3dc04f693b6037fc539fcff896a72c083 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Sat, 13 Sep 2025 10:54:28 -0700
Subject: [PATCH 04/14] complete machines docs

---
 .../backend/machines/create-scope.mdx         | 35 +++++++++++++++++-
 docs/references/backend/machines/create.mdx   | 14 ++++++-
 .../backend/machines/delete-scope.mdx         | 37 ++++++++++++++++++-
 docs/references/backend/machines/list.mdx     |  2 +-
 docs/references/backend/machines/update.mdx   |  8 ++--
 5 files changed, 87 insertions(+), 9 deletions(-)

diff --git a/docs/references/backend/machines/create-scope.mdx b/docs/references/backend/machines/create-scope.mdx
index ffa323e8a4..0cba16a613 100644
--- a/docs/references/backend/machines/create-scope.mdx
+++ b/docs/references/backend/machines/create-scope.mdx
@@ -4,8 +4,39 @@ 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.
+Creates a new machine scope, allowing the specified machine to access another machine. Machine scopes define which machines can interact with each other in your application.
 
 ```ts
-function create(machineId: string, toMachineId: string): Promise<MachineScope>
+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.
diff --git a/docs/references/backend/machines/create.mdx b/docs/references/backend/machines/create.mdx
index e771664332..b608bd1d3c 100644
--- a/docs/references/backend/machines/create.mdx
+++ b/docs/references/backend/machines/create.mdx
@@ -4,7 +4,7 @@ description: Use Clerk's Backend SDK to create a machine.
 sdk: js-backend
 ---
 
-Creates a new machine.
+Creates a new machine..
 
 ```ts
 function create(params: CreateMachineParams): Promise<Machine>
@@ -37,12 +37,24 @@ function create(params: CreateMachineParams): Promise<Machine>
 
 <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.
diff --git a/docs/references/backend/machines/delete-scope.mdx b/docs/references/backend/machines/delete-scope.mdx
index a10f0b3428..9115ccadd1 100644
--- a/docs/references/backend/machines/delete-scope.mdx
+++ b/docs/references/backend/machines/delete-scope.mdx
@@ -4,4 +4,39 @@ description: Use Clerk's Backend SDK to delete a machine scope.
 sdk: js-backend
 ---
 
-Deletes a machine scope.
+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.
\ No newline at end of file
diff --git a/docs/references/backend/machines/list.mdx b/docs/references/backend/machines/list.mdx
index 8415093a2f..cd8b00641a 100644
--- a/docs/references/backend/machines/list.mdx
+++ b/docs/references/backend/machines/list.mdx
@@ -4,7 +4,7 @@ description: Use Clerk's Backend SDK to get a list of machines for your applicat
 sdk: js-backend
 ---
 
-Retrieves a list of machines for your application, sorted by descending creation date.
+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`](/docs/references/backend/types/backend-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(
diff --git a/docs/references/backend/machines/update.mdx b/docs/references/backend/machines/update.mdx
index 81be9ddf51..25cfe2c3a9 100644
--- a/docs/references/backend/machines/update.mdx
+++ b/docs/references/backend/machines/update.mdx
@@ -1,5 +1,5 @@
 ---
-title: '`delete()`'
+title: '`update()`'
 description: Use Clerk's Backend SDK to update a machine.
 sdk: js-backend
 ---
@@ -10,15 +10,15 @@ Updates a machine by its ID.
 function update(params: UpdateMachineParams): Promise<Machine>
 ```
 
-## Parameters
+## `UpdateMachineParams`
 
 <Properties>
   - `machineId`
   - `string`
 
-    The ID of the machine to update.
+  The ID of the machine to update.
 
-    ---
+  ---
 
   - `name`
   - `string`

From 5c3cf413c3b425f547c41d1f596b33c92b9faec8 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Sat, 13 Sep 2025 10:57:04 -0700
Subject: [PATCH 05/14] chore: run format

---
 docs/references/backend/machines/create.mdx       | 4 ++--
 docs/references/backend/machines/delete-scope.mdx | 2 +-
 docs/references/backend/machines/list.mdx         | 4 +---
 docs/references/backend/machines/update.mdx       | 2 +-
 4 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/references/backend/machines/create.mdx b/docs/references/backend/machines/create.mdx
index b608bd1d3c..949a6b4d32 100644
--- a/docs/references/backend/machines/create.mdx
+++ b/docs/references/backend/machines/create.mdx
@@ -41,7 +41,7 @@ function create(params: CreateMachineParams): Promise<Machine>
 
 ```ts
 const response = await clerkClient.machines.create({
-  name: 'Email Server'
+  name: 'Email Server',
 })
 ```
 
@@ -51,7 +51,7 @@ const response = await clerkClient.machines.create({
 const response = await clerkClient.machines.create({
   name: 'API Gateway',
   scopedMachines: ['mch_123', 'mch_456'],
-  defaultTokenTtl: 3600
+  defaultTokenTtl: 3600,
 })
 ```
 
diff --git a/docs/references/backend/machines/delete-scope.mdx b/docs/references/backend/machines/delete-scope.mdx
index 9115ccadd1..ed3368973e 100644
--- a/docs/references/backend/machines/delete-scope.mdx
+++ b/docs/references/backend/machines/delete-scope.mdx
@@ -39,4 +39,4 @@ const response = await clerkClient.machines.deleteScope(machineId, otherMachineI
 
 ## 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.
\ No newline at end of file
+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.
diff --git a/docs/references/backend/machines/list.mdx b/docs/references/backend/machines/list.mdx
index cd8b00641a..00e325f4ca 100644
--- a/docs/references/backend/machines/list.mdx
+++ b/docs/references/backend/machines/list.mdx
@@ -7,9 +7,7 @@ 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`](/docs/references/backend/types/backend-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[]>>
+function list(params: GetMachineListParams = {}): Promise<PaginatedResourceResponse<Machine[]>>
 ```
 
 ## Parameters
diff --git a/docs/references/backend/machines/update.mdx b/docs/references/backend/machines/update.mdx
index 25cfe2c3a9..4251dec822 100644
--- a/docs/references/backend/machines/update.mdx
+++ b/docs/references/backend/machines/update.mdx
@@ -43,7 +43,7 @@ const machineId = 'mch_123'
 const response = await clerkClient.machines.update({
   machineId,
   name: 'New Machine Name',
-  defaultTokenTtl: 3600
+  defaultTokenTtl: 3600,
 })
 ```
 

From 36e52ec5ed6606bad4722c9594d0f16317c9442f Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Sat, 13 Sep 2025 11:04:47 -0700
Subject: [PATCH 06/14] chore: run format

---
 docs/custom-flows/forgot-password.mdx | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/custom-flows/forgot-password.mdx b/docs/custom-flows/forgot-password.mdx
index 6310505890..883857c597 100644
--- a/docs/custom-flows/forgot-password.mdx
+++ b/docs/custom-flows/forgot-password.mdx
@@ -138,9 +138,7 @@ This guide demonstrates how to use Clerk's API to build a custom flow for resett
                 <label htmlFor="password">Enter your new password</label>
                 <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
 
-                <label htmlFor="code">
-                  Enter the password reset code that was sent to your email
-                </label>
+                <label htmlFor="code">Enter the password reset code that was sent to your email</label>
                 <input type="text" value={code} onChange={(e) => setCode(e.target.value)} />
 
                 <button>Reset</button>

From 6af3cc97c302518990a296c02b7de9931d074888 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Sun, 14 Sep 2025 10:09:50 -0700
Subject: [PATCH 07/14] chore: remove missing link

---
 docs/references/backend/machines/list.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/references/backend/machines/list.mdx b/docs/references/backend/machines/list.mdx
index 00e325f4ca..da87cd024e 100644
--- a/docs/references/backend/machines/list.mdx
+++ b/docs/references/backend/machines/list.mdx
@@ -4,7 +4,7 @@ description: Use Clerk's Backend SDK to get a list of machines for your applicat
 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`](/docs/references/backend/types/backend-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.
+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[]>>

From f15f74363b348eee8a2c2a2fbccbe9fe84e45f05 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 15 Sep 2025 09:30:31 -0700
Subject: [PATCH 08/14] remove extra period

---
 docs/references/backend/machines/create-scope.mdx | 2 +-
 docs/references/backend/machines/create.mdx       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/references/backend/machines/create-scope.mdx b/docs/references/backend/machines/create-scope.mdx
index 0cba16a613..6bbbbb7307 100644
--- a/docs/references/backend/machines/create-scope.mdx
+++ b/docs/references/backend/machines/create-scope.mdx
@@ -4,7 +4,7 @@ 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. Machine scopes define which machines can interact with each other in your application.
+Creates a new machine scope, allowing the specified machine to access another machine.
 
 ```ts
 function createScope(machineId: string, toMachineId: string): Promise<MachineScope>
diff --git a/docs/references/backend/machines/create.mdx b/docs/references/backend/machines/create.mdx
index 949a6b4d32..d69a96c83b 100644
--- a/docs/references/backend/machines/create.mdx
+++ b/docs/references/backend/machines/create.mdx
@@ -4,7 +4,7 @@ description: Use Clerk's Backend SDK to create a machine.
 sdk: js-backend
 ---
 
-Creates a new machine..
+Creates a new machine.
 
 ```ts
 function create(params: CreateMachineParams): Promise<Machine>

From 10d88cbb9eb5f2278af6bff3bf97c266a31f2db7 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 15 Sep 2025 09:34:08 -0700
Subject: [PATCH 09/14] turn off formatting in delete method

---
 docs/references/backend/machines/create.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/references/backend/machines/create.mdx b/docs/references/backend/machines/create.mdx
index d69a96c83b..a1be5a3ba2 100644
--- a/docs/references/backend/machines/create.mdx
+++ b/docs/references/backend/machines/create.mdx
@@ -6,7 +6,7 @@ sdk: js-backend
 
 Creates a new machine.
 
-```ts
+```ts {{ prettier: false }}
 function create(params: CreateMachineParams): Promise<Machine>
 ```
 

From 833e9cdb4b76e5efb84f0b44ea0b7b67921c27b0 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 15 Sep 2025 09:35:40 -0700
Subject: [PATCH 10/14] turn off formatting in delete method

---
 docs/references/backend/machines/create.mdx | 2 +-
 docs/references/backend/machines/delete.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/references/backend/machines/create.mdx b/docs/references/backend/machines/create.mdx
index a1be5a3ba2..d69a96c83b 100644
--- a/docs/references/backend/machines/create.mdx
+++ b/docs/references/backend/machines/create.mdx
@@ -6,7 +6,7 @@ sdk: js-backend
 
 Creates a new machine.
 
-```ts {{ prettier: false }}
+```ts
 function create(params: CreateMachineParams): Promise<Machine>
 ```
 
diff --git a/docs/references/backend/machines/delete.mdx b/docs/references/backend/machines/delete.mdx
index d7afe7e47f..593a5c7d27 100644
--- a/docs/references/backend/machines/delete.mdx
+++ b/docs/references/backend/machines/delete.mdx
@@ -6,7 +6,7 @@ sdk: js-backend
 
 Deletes a machine by its ID.
 
-```ts
+```ts {{ prettier: false }}
 function delete(machineId: string): Promise<Machine>
 ```
 

From ae1cabb8b967ca92df84284043d03160a3dff75c Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 15 Sep 2025 16:03:18 -0700
Subject: [PATCH 11/14] fix incorrect rotate secret key params type

---
 docs/references/backend/machines/rotate-secret-key.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/references/backend/machines/rotate-secret-key.mdx b/docs/references/backend/machines/rotate-secret-key.mdx
index f4aa4221f3..e37eb2893b 100644
--- a/docs/references/backend/machines/rotate-secret-key.mdx
+++ b/docs/references/backend/machines/rotate-secret-key.mdx
@@ -7,7 +7,7 @@ sdk: js-backend
 Rotates the machine secret key for a given machine by its ID.
 
 ```ts
-function rotateSecretKey(machineId: string): Promise<MachineSecretKey>
+function rotateSecretKey(params: RotateMachineSecretKeyParams): Promise<MachineSecretKey>
 ```
 
 ## Parameters

From f168b95710b7cbc013450d6ce7302c1fb149487c Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 15 Sep 2025 16:04:18 -0700
Subject: [PATCH 12/14] add missing previousTokenTtl to rotate secret key

---
 docs/references/backend/machines/rotate-secret-key.mdx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/references/backend/machines/rotate-secret-key.mdx b/docs/references/backend/machines/rotate-secret-key.mdx
index e37eb2893b..d9508411fa 100644
--- a/docs/references/backend/machines/rotate-secret-key.mdx
+++ b/docs/references/backend/machines/rotate-secret-key.mdx
@@ -17,6 +17,13 @@ function rotateSecretKey(params: RotateMachineSecretKeyParams): Promise<MachineS
   - `string`
 
   The ID of the machine for which to rotate the secret key.
+
+  ---
+
+  - `previousTokenTtl`
+  - `number`
+
+  The time in seconds that the previous secret key will remain valid after rotation.
 </Properties>
 
 ## Example

From d7f0790347dea3ced1e7e6295292e7a6e50396bd Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 15 Sep 2025 16:04:51 -0700
Subject: [PATCH 13/14] update example

---
 docs/references/backend/machines/rotate-secret-key.mdx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/references/backend/machines/rotate-secret-key.mdx b/docs/references/backend/machines/rotate-secret-key.mdx
index d9508411fa..00f155c53e 100644
--- a/docs/references/backend/machines/rotate-secret-key.mdx
+++ b/docs/references/backend/machines/rotate-secret-key.mdx
@@ -33,7 +33,10 @@ function rotateSecretKey(params: RotateMachineSecretKeyParams): Promise<MachineS
 ```ts
 const machineId = 'mch_123'
 
-const response = await clerkClient.machines.rotateSecretKey(machineId)
+const response = await clerkClient.machines.rotateSecretKey({
+  machineId,
+  previousTokenTtl: 3600,
+})
 ```
 
 ## Backend API (BAPI) endpoint

From 4f1ea4b76c870d04f4ad86742a5c6862dd4ac37a Mon Sep 17 00:00:00 2001
From: Robert Soriano <sorianorobertc@gmail.com>
Date: Tue, 16 Sep 2025 13:02:31 -0700
Subject: [PATCH 14/14] Update docs/references/backend/machines/update.mdx

Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
---
 docs/references/backend/machines/update.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/references/backend/machines/update.mdx b/docs/references/backend/machines/update.mdx
index 4251dec822..17eb597eb2 100644
--- a/docs/references/backend/machines/update.mdx
+++ b/docs/references/backend/machines/update.mdx
@@ -20,7 +20,7 @@ function update(params: UpdateMachineParams): Promise<Machine>
 
   ---
 
-  - `name`
+  - `name?`
   - `string`
 
   The name of the machine.