Clerk API (unofficial showcase)
POST/scim_directories

Create a SCIM directory

Creates a SCIM directory for the instance and associates it with an enterprise connection. Supply enterprise_connection_id and provider; you can also include group-to-role mappings to create with the directory. The created directory response includes its SCIM endpoint URL and API key.

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

4 body fields

SCIM 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 SCIM group to organization role mappings to create with the directory.

5 status codes
200Returns the created directory configuration, including its identifier, SCIM endpoint URL, provider, settings, timestamps, and API key.
objectstringrequired
String representing the object's type. Always "scim_directory".
Allowed:scim_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 SCIM 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 SCIM attribute paths they are extracted from.
custom_attributesarray<object>optional
Custom attributes to map from the IdP to the user's profile via SCIM provisioning. Requires the custom attributes feature to be enabled for the instance.
api_keystringoptional
The API key for authenticating SCIM 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 indicates the request was not successful, a 401 indicates invalid authentication, a 403 indicates invalid authorization, and a 422 indicates invalid request parameters. enterprise_connection_id and provider are required; each group_role_mappings item must include scim_group_id and role_id, and scim_group_display_name is limited to 255 characters. precedence must be at least 1 when supplied; if omitted, it is assigned by array order.