Clerk API (unofficial showcase)
POST/machines

Create a machine

Creates a new machine. Provide a name and optionally configure its machine scopes and default token TTL. The response includes the machine's secret key, so store it securely.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

3 body fields

Machine configuration. Provide name; scoped_machines and default_token_ttl are optional.

namestringrequired
The name of the machine
scoped_machinesarray<string>optional
Array of machine IDs that this machine will have access to. Maximum of 150 scopes per machine.
default_token_ttlintegeroptional
The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second.
Default:3600

5 status codes
200Returns the created machine details and its `secret_key`.
objectstringrequired
Allowed:machine
idstringrequired
Unique identifier for the machine.
namestringrequired
The name of the machine.
instance_idstringrequired
The ID of the instance this machine belongs to.
created_atintegerrequired
Unix timestamp of creation.
updated_atintegerrequired
Unix timestamp of last update.
default_token_ttlintegeroptional
The default time-to-live (TTL) in seconds for tokens created by this machine.
Default:3600
scoped_machinesarray<object>required
Array of machines this machine has access to.
secret_keystringrequired
The secret key for the machine, only returned upon creation.
400Returned when the request is not successful.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Returned when authentication is invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Returned when authorization is invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Returned when request parameters are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 indicates the request was not successful, a 401 indicates invalid authentication, a 403 indicates invalid authorization, and a 422 indicates invalid request parameters. name must be 1 to 255 characters, scoped_machines can contain at most 150 machine IDs, and default_token_ttl must be between 1 and 315360000 seconds; it defaults to 3600 when omitted.