chore(backend): Add machine secret key rotation BAPI method (#6760)

Author: wobsoriano

.changeset/angry-impalas-draw.md

@@ -0,0 +1,14 @@
+---
+"@clerk/backend": patch
+---
+
+Add machine secret key rotation BAPI method
+
+Usage:
+
+```ts
+clerkClient.machines.rotateSecretKey({
+  machineId: 'mch_xxx',
+  previousTokenTtl: 3600,
+})
+```

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

@@ -171,6 +171,26 @@ describe('MachineAPI', () => {
     expect(response.secret).toBe('ak_test_...');
   });
 
+  it('rotates a machine secret key', async () => {
+    server.use(
+      http.post(
+        `https://api.clerk.test/v1/machines/${machineId}/secret_key/rotate`,
+        validateHeaders(() => {
+          return HttpResponse.json({
+            secret: 'ak_updated_...',
+          });
+        }),
+      ),
+    );
+
+    const response = await apiClient.machines.rotateSecretKey({
+      machineId,
+      previousTokenTtl: 3600,
+    });
+
+    expect(response.secret).toBe('ak_updated_...');
+  });
+
   it('creates a machine scope', async () => {
     server.use(
       http.post(

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

@@ -43,6 +43,17 @@ type GetMachineListParams = {
   query?: string;
 };
 
+type RotateMachineSecretKeyParams = {
+  /**
+   * The ID of the machine to rotate the secret key for.
+   */
+  machineId: string;
+  /**
+   * The time in seconds that the previous secret key will remain valid after rotation.
+   */
+  previousTokenTtl: number;
+};
+
 export class MachineApi extends AbstractAPI {
   async get(machineId: string) {
     this.requireId(machineId);
@@ -94,6 +105,18 @@ export class MachineApi extends AbstractAPI {
     });
   }
 
+  async rotateSecretKey(params: RotateMachineSecretKeyParams) {
+    const { machineId, previousTokenTtl } = params;
+    this.requireId(machineId);
+    return this.request<MachineSecretKey>({
+      method: 'POST',
+      path: joinPaths(basePath, machineId, 'secret_key', 'rotate'),
+      bodyParams: {
+        previousTokenTtl,
+      },
+    });
+  }
+
   /**
    * Creates a new machine scope, allowing the specified machine to access another machine.
    *