Clerk API (unofficial showcase)
POST/machines/{machine_id}/secret_key/rotate

Rotate a machine's 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.

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

1 parameter · 1 body field
machine_idstringrequired
The ID of the machine to rotate the secret key for
previous_token_ttlintegerrequired
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).

6 status codes
200Success
objectstringrequired
String representing the object's type.
Allowed:machine_secret_key
secretstringrequired
The secret key for the machine.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.