Clerk docs

Machines

A Machine represents a machine/server/service which can be used in machine-to-machine authentication.

Get a list of machines for an instance

This request returns the list of machines for an instance. The machines are ordered by descending creation date (i.e. most recent machines will be returned first)

SecuritybearerAuth
Request
query Parameters
limit
integer [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset.

offset
integer >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

query
string

Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

422

Invalid request parameters

get/machines
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Create a machine

Creates a new machine.

SecuritybearerAuth
Request
Request Body schema: application/json
name
required
string [ 1 .. 255 ] characters

The name of the machine

Responses
200

Success

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

422

Invalid request parameters

post/machines
Request samples
application/json
{
  • "name": "string"
}
Response samples
application/json
{
  • "object": "machine",
  • "id": "string",
  • "name": "string",
  • "instance_id": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Retrieve a machine

Returns the details of a machine.

SecuritybearerAuth
Request
path Parameters
machine_id
required
string

The ID of the machine to retrieve

Responses
200

Success

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

get/machines/{machine_id}
Response samples
application/json
{
  • "object": "machine",
  • "id": "string",
  • "name": "string",
  • "instance_id": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Update a machine

Updates an existing machine. Only the provided fields will be updated.

SecuritybearerAuth
Request
path Parameters
machine_id
required
string

The ID of the machine to update

Request Body schema: application/json
name
string [ 1 .. 255 ] characters

The name of the machine

Responses
200

Success

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

patch/machines/{machine_id}
Request samples
application/json
{
  • "name": "string"
}
Response samples
application/json
{
  • "object": "machine",
  • "id": "string",
  • "name": "string",
  • "instance_id": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Delete a machine

Deletes a machine.

SecuritybearerAuth
Request
path Parameters
machine_id
required
string

The ID of the machine to delete

Responses
200

Success

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

delete/machines/{machine_id}
Response samples
application/json
{
  • "object": "machine",
  • "id": "string",
  • "deleted": true
}
➔ Next to Sign-in Tokens