Clerk API (unofficial showcase)
POST/directories

Create a directory

Creates a directory for provisioning users from an identity provider and associates it with an enterprise connection. Supply enterprise_connection_id and provider; optionally include a name and group-to-role mappings to create with the directory. The response includes the directory configuration and its API key.

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

4 body fields

Directory configuration, with optional group-to-role mappings to create alongside the directory.

enterprise_connection_idstringrequired
The ID of the enterprise connection to associate with this directory.
namestringoptional
A human-friendly name for the directory.
providerstringrequired
The identity provider for this directory.
group_role_mappingsarray<object>optional
Optional directory group to organization role mappings to create with the directory.

5 status codes
200Returns the created directory configuration, including its unique ID, provisioning endpoint URL, provider, enabled state, attribute mapping, and timestamps. The API key is returned when the directory is created.
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
422Returned when request parameters are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned when the request is unsuccessful. A 401 is returned when authentication is invalid. A 403 is returned when authorization is invalid. A 422 is returned when request parameters are invalid. enterprise_connection_id and provider are required. Each group-role mapping must include role_id and exactly one of directory_group_id or scim_group_id; if you send both legacy and current field names, their values must match.