Clerk API (unofficial showcase)
POST/directories/{directory_id}/rotate_api_key

Rotate a directory's API key

Generates a new API key for the directory and returns it in the api_key field. This is the only way to obtain the key after creation, so make sure to update it in your identity provider. The previous key remains valid for a short grace period before it expires.

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

1 parameter
directory_idstringrequired
The ID of the directory whose API key to rotate

5 status codes
200A directory
objectstringrequired
String representing the object's type. Always "directory".
Allowed:directory
idstringrequired
Unique identifier for the directory.
namestringrequired
A human-friendly name for the directory.
enterprise_connection_idstringoptional
The ID of the associated enterprise connection.
endpoint_urlstringrequired
The provisioning endpoint URL for this directory.
providerstringrequired
The identity provider for this directory.
enabledbooleanrequired
Whether the directory is enabled.
group_role_mapping_enabledbooleanrequired
Whether group-to-role mapping is enabled for this directory.
attribute_mappingobjectrequired
Mapping of user attributes to the directory attribute paths they are extracted from.
custom_attributesarray<object>optional
Custom attributes to map from the IdP to the user's profile via directory sync. Requires the custom attributes feature to be enabled for the instance.
api_keystringoptional
The API key for authenticating provisioning requests. Only returned when the directory is created or the key is rotated.
created_atintegerrequired
Unix timestamp when the directory was created.
updated_atintegerrequired
Unix timestamp when the directory was last updated.
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 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.