chore(backend): Add machines Backend API resource and methods (#6335)

wobsoriano · web-flow · commit 5fbf8df84b6d · 2025-07-16T10:25:03.000-07:00
diff --git a/.changeset/eleven-cats-greet.md b/.changeset/eleven-cats-greet.md
@@ -0,0 +1,5 @@
+---
+"@clerk/backend": minor
+---
+
+Add machines Backend API resource and methods
diff --git a/packages/backend/src/api/endpoints/MachineApi.ts b/packages/backend/src/api/endpoints/MachineApi.ts
@@ -0,0 +1,65 @@
+import { joinPaths } from '../../util/path';
+import type { PaginatedResourceResponse } from '../resources/Deserializer';
+import type { Machine } from '../resources/Machine';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/machines';
+
+type CreateMachineParams = {
+  name: string;
+};
+
+type UpdateMachineParams = {
+  machineId: string;
+  name: string;
+};
+
+type GetMachineListParams = {
+  limit?: number;
+  offset?: number;
+  query?: string;
+};
+
+export class MachineApi extends AbstractAPI {
+  async get(machineId: string) {
+    this.requireId(machineId);
+    return this.request<Machine>({
+      method: 'GET',
+      path: joinPaths(basePath, machineId),
+    });
+  }
+
+  async list(queryParams: GetMachineListParams = {}) {
+    return this.request<PaginatedResourceResponse<Machine[]>>({
+      method: 'GET',
+      path: basePath,
+      queryParams,
+    });
+  }
+
+  async create(bodyParams: CreateMachineParams) {
+    return this.request<Machine>({
+      method: 'POST',
+      path: basePath,
+      bodyParams,
+    });
+  }
+
+  async update(params: UpdateMachineParams) {
+    const { machineId, ...bodyParams } = params;
+    this.requireId(machineId);
+    return this.request<Machine>({
+      method: 'PATCH',
+      path: joinPaths(basePath, machineId),
+      bodyParams,
+    });
+  }
+
+  async delete(machineId: string) {
+    this.requireId(machineId);
+    return this.request<Machine>({
+      method: 'DELETE',
+      path: joinPaths(basePath, machineId),
+    });
+  }
+}
diff --git a/packages/backend/src/api/endpoints/index.ts b/packages/backend/src/api/endpoints/index.ts
@@ -11,6 +11,7 @@ export * from './EmailAddressApi';
 export * from './IdPOAuthAccessTokenApi';
 export * from './InstanceApi';
 export * from './InvitationApi';
+export * from './MachineApi';
 export * from './MachineTokensApi';
 export * from './JwksApi';
 export * from './JwtTemplatesApi';
diff --git a/packages/backend/src/api/factory.ts b/packages/backend/src/api/factory.ts
@@ -13,6 +13,7 @@ import {
   InvitationAPI,
   JwksAPI,
   JwtTemplatesApi,
+  MachineApi,
   MachineTokensApi,
   OAuthApplicationsApi,
   OrganizationAPI,
@@ -64,6 +65,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
     invitations: new InvitationAPI(request),
     jwks: new JwksAPI(request),
     jwtTemplates: new JwtTemplatesApi(request),
+    machines: new MachineApi(request),
     machineTokens: new MachineTokensApi(
       buildRequest({
         ...options,
diff --git a/packages/backend/src/api/resources/Deserializer.ts b/packages/backend/src/api/resources/Deserializer.ts
@@ -15,6 +15,7 @@ import {
   InstanceSettings,
   Invitation,
   JwtTemplate,
+  Machine,
   MachineToken,
   OauthAccessToken,
   OAuthApplication,
@@ -132,6 +133,8 @@ function jsonToObject(item: any): any {
       return Invitation.fromJSON(item);
     case ObjectType.JwtTemplate:
       return JwtTemplate.fromJSON(item);
+    case ObjectType.Machine:
+      return Machine.fromJSON(item);
     case ObjectType.MachineToken:
       return MachineToken.fromJSON(item);
     case ObjectType.OauthAccessToken:
diff --git a/packages/backend/src/api/resources/JSON.ts b/packages/backend/src/api/resources/JSON.ts
@@ -34,6 +34,7 @@ export const ObjectType = {
   InstanceRestrictions: 'instance_restrictions',
   InstanceSettings: 'instance_settings',
   Invitation: 'invitation',
+  Machine: 'machine',
   MachineToken: 'machine_to_machine_token',
   JwtTemplate: 'jwt_template',
   OauthAccessToken: 'oauth_access_token',
@@ -698,6 +699,15 @@ export interface SamlAccountConnectionJSON extends ClerkResourceJSON {
   updated_at: number;
 }
 
+export interface MachineJSON extends ClerkResourceJSON {
+  object: typeof ObjectType.Machine;
+  id: string;
+  name: string;
+  instance_id: string;
+  created_at: number;
+  updated_at: number;
+}
+
 export interface MachineTokenJSON extends ClerkResourceJSON {
   object: typeof ObjectType.MachineToken;
   name: string;
diff --git a/packages/backend/src/api/resources/Machine.ts b/packages/backend/src/api/resources/Machine.ts
@@ -0,0 +1,15 @@
+import type { MachineJSON } from './JSON';
+
+export class Machine {
+  constructor(
+    readonly id: string,
+    readonly name: string,
+    readonly instanceId: string,
+    readonly createdAt: number,
+    readonly updatedAt: number,
+  ) {}
+
+  static fromJSON(data: MachineJSON): Machine {
+    return new Machine(data.id, data.name, data.instance_id, data.created_at, data.updated_at);
+  }
+}
diff --git a/packages/backend/src/api/resources/index.ts b/packages/backend/src/api/resources/index.ts
@@ -30,6 +30,7 @@ export * from './InstanceRestrictions';
 export * from './InstanceSettings';
 export * from './Invitation';
 export * from './JSON';
+export * from './Machine';
 export * from './MachineToken';
 export * from './JwtTemplate';
 export * from './OauthAccessToken';

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@clerk/backend": minor
 +---
++
 +Add machines Backend API resource and methods