diff --git a/docs/manifest.json b/docs/manifest.json index 50f70db314..0c1d6cea9e 100644 --- a/docs/manifest.json +++ b/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, diff --git a/docs/references/backend/machines/create-scope.mdx b/docs/references/backend/machines/create-scope.mdx new file mode 100644 index 0000000000..6bbbbb7307 --- /dev/null +++ b/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 +``` + +## Parameters + + + - `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. + + +## Example + + + +```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 new file mode 100644 index 0000000000..d69a96c83b --- /dev/null +++ b/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 +``` + +## `CreateMachineParams` + + + - `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. + + +## Example + + + +### 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 new file mode 100644 index 0000000000..ed3368973e --- /dev/null +++ b/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 +``` + +## Parameters + + + - `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. + + +## Example + + + +```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. diff --git a/docs/references/backend/machines/delete.mdx b/docs/references/backend/machines/delete.mdx new file mode 100644 index 0000000000..593a5c7d27 --- /dev/null +++ b/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 +``` + +## Parameters + + + - `machineId` + - `string` + + The ID of the machine to delete. + + +## Example + + + +```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 new file mode 100644 index 0000000000..33c0065bd5 --- /dev/null +++ b/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 +``` + +## Parameters + + + - `machineId` + - `string` + + The ID of the machine for which to retrieve the secret key. + + +## Example + + + +```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 new file mode 100644 index 0000000000..9f4a51f59f --- /dev/null +++ b/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 +``` + +## Parameters + + + - `machineId` + - `string` + + The ID of the machine to retrieve. + + +## Example + + + +```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/list.mdx b/docs/references/backend/machines/list.mdx new file mode 100644 index 0000000000..da87cd024e --- /dev/null +++ b/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> +``` + +## Parameters + + + - `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. + + +## Examples + + + +### 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/rotate-secret-key.mdx b/docs/references/backend/machines/rotate-secret-key.mdx new file mode 100644 index 0000000000..00f155c53e --- /dev/null +++ b/docs/references/backend/machines/rotate-secret-key.mdx @@ -0,0 +1,44 @@ +--- +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(params: RotateMachineSecretKeyParams): Promise +``` + +## Parameters + + + - `machineId` + - `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. + + +## Example + + + +```ts +const machineId = 'mch_123' + +const response = await clerkClient.machines.rotateSecretKey({ + machineId, + previousTokenTtl: 3600, +}) +``` + +## 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. diff --git a/docs/references/backend/machines/update.mdx b/docs/references/backend/machines/update.mdx new file mode 100644 index 0000000000..17eb597eb2 --- /dev/null +++ b/docs/references/backend/machines/update.mdx @@ -0,0 +1,52 @@ +--- +title: '`update()`' +description: Use Clerk's Backend SDK to update a machine. +sdk: js-backend +--- + +Updates a machine by its ID. + +```ts +function update(params: UpdateMachineParams): Promise +``` + +## `UpdateMachineParams` + + + - `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. + + +## Example + + + +```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.