Machines

Overview

Available Operations

list - Get a list of machines for an instance
create - Create a machine
get - Retrieve a machine
update - Update a machine
delete - Delete a machine
get_secret_key - Retrieve a machine secret key
rotate_secret_key - Rotate a machine's secret key
create_scope - Create a machine scope
delete_scope - Delete a machine scope

list

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)

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.list(limit=20, offset=10, query="<value>", order_by="-created_at")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`limit`	Optional[int]	➖	Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.	20
`offset`	Optional[int]	➖	Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`.	10
`query`	Optional[str]	➖	Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name.
`order_by`	Optional[str]	➖	Allows to return machines in a particular order. You can order the returned machines by their `name` or `created_at`. To specify the direction, use the `+` or `-` symbols prepended to the property to order by. For example, to return machines in descending order by `created_at`, use `-created_at`. If you don't use `+` or `-`, then `+` is implied. Defaults to `-created_at`.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.MachineList

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 422	application/json
models.SDKError	4XX, 5XX	/

create

Creates a new machine.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.create(request={
        "name": "<value>",
        "scoped_machines": [
            "<value 1>",
            "<value 2>",
            "<value 3>",
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`request`	models.CreateMachineRequestBody	✔️	The request object to use for the request.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.MachineCreated

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 422	application/json
models.SDKError	4XX, 5XX	/

get

Returns the details of a machine.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.get(machine_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`machine_id`	str	✔️	The ID of the machine to retrieve
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Machine

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.SDKError	4XX, 5XX	/

update

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

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.update(machine_id="<id>", name="<value>", default_token_ttl=754540)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`machine_id`	str	✔️	The ID of the machine to update
`name`	Optional[str]	➖	The name of the machine
`default_token_ttl`	Optional[int]	➖	The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Machine

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.SDKError	4XX, 5XX	/

delete

Deletes a machine.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.delete(machine_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`machine_id`	str	✔️	The ID of the machine to delete
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.MachineDeleted

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.SDKError	4XX, 5XX	/

get_secret_key

Returns the secret key for a machine.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.get_secret_key(machine_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`machine_id`	str	✔️	The ID of the machine to retrieve the secret key for
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.MachineSecretKey

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404	application/json
models.SDKError	4XX, 5XX	/

rotate_secret_key

Rotates the machine's secret key. When the secret key is rotated, make sure to update it in your machine/application. The previous secret key will remain valid for the duration specified by the previous_token_ttl parameter.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.rotate_secret_key(machine_id="<id>", previous_token_ttl=632625)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`machine_id`	str	✔️	The ID of the machine to rotate the secret key for
`previous_token_ttl`	int	✔️	The time in seconds that the previous secret key will remain valid after rotation. This ensures a graceful transition period for updating applications with the new secret key. Set to 0 to immediately expire the previous key. Maximum value is 8 hours (28800 seconds).
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.MachineSecretKey

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.SDKError	4XX, 5XX	/

create_scope

Creates a new machine scope, allowing the specified machine to access another machine. Maximum of 150 scopes per machine.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.create_scope(machine_id="<id>", to_machine_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`machine_id`	str	✔️	The ID of the machine that will have access to another machine
`to_machine_id`	str	✔️	The ID of the machine that will be scoped to the current machine
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.MachineScope

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 409, 422	application/json
models.SDKError	4XX, 5XX	/

delete_scope

Deletes a machine scope, removing access from one machine to another.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.machines.delete_scope(machine_id="<id>", other_machine_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`machine_id`	str	✔️	The ID of the machine that has access to another machine
`other_machine_id`	str	✔️	The ID of the machine that is being accessed
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.MachineScopeDeleted

Errors

Error Type	Status Code	Content Type
models.ClerkErrors	400, 401, 403, 404, 422	application/json
models.SDKError	4XX, 5XX	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Machines

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

get_secret_key

Example Usage

Parameters

Response

Errors

rotate_secret_key

Example Usage

Parameters

Response

Errors

create_scope

Example Usage

Parameters

Response

Errors

delete_scope

Example Usage

Parameters

Response

Errors