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

Retrieve a directory

Retrieves the configuration for a directory used to provision users from an identity provider. Use directory_id to identify the directory whose details you need.

1 parameter
directory_idstringrequired
The ID of the directory to retrieve.

4 status codes
200Returns the 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.
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

Error handling

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. The directory_id path parameter must identify an existing directory.