Clerk API (unofficial showcase)
PATCH/directories/{directory_id}

Update a directory

Updates configurable properties of a directory used to provision users from an identity provider. Supply only the fields you want to change; attribute_mapping entries are merged into the existing mapping, and a key set to null is removed.

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

1 parameter · 5 body fields
directory_idstringrequired
The ID of the directory to update.

Optional directory fields to update; send only the properties you want to change.

namestringoptional
A human-friendly name for the directory.
enabledbooleanoptional
Whether the directory is enabled.
providerstringoptional
The identity provider for this directory.
attribute_mappingobjectoptional
Attribute-to-directory-path entries to merge into the directory's attribute mapping. Set a key to `null` to remove it from the mapping.
group_role_mapping_enabledbooleanoptional
Whether group-to-role mapping is enabled for this directory.

6 status codes
200Returns the updated directory configuration, including its ID, name, associated enterprise connection, provisioning endpoint URL, provider, enabled state, attribute mapping, and timestamps. The API key is included only when the directory is created or its key is rotated.
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.
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
404Returned when the directory is not found.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Returned when request parameters are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned when the request is not successful. A 401 is returned when authentication is invalid. A 403 is returned when authorization is invalid. A 404 is returned when the directory is not found. A 422 is returned when request parameters are invalid. The directory_id path parameter must identify an existing directory. All body fields are optional; use attribute_mapping to merge entries or set a key to null to remove it.