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

Create a directory group role mapping

Creates a new directory group to organization role mapping for a directory. Mappings can be created while group role mapping is disabled on the directory, but they only take effect once it is enabled.

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

1 parameter · 4 body fields
directory_idstringrequired
The ID of the directory.
directory_group_idstringoptional
The group ID from the identity provider. Exactly one of `directory_group_id` or `scim_group_id` is required.
scim_group_idstringoptional
The legacy name for `directory_group_id`. Send either one, or both with the same value; sending both with different values is rejected.
role_idstringrequired
The ID of the organization role to assign to members of the group.
precedenceintegeroptional
The precedence for this mapping. Lower values take priority when a user belongs to multiple mapped groups. If omitted, the mapping is appended with the next-highest precedence.

6 status codes
200A directory group role mapping
objectstringrequired
String representing the object's type. Always "directory_group_role_mapping".
Allowed:directory_group_role_mapping
idstringrequired
Unique identifier for the directory group role mapping.
directory_idstringrequired
The ID of the directory this mapping belongs to.
scim_directory_idstringrequired
The legacy name for `directory_id`. Carries the same value.
directory_group_idstringrequired
The group ID from the identity provider.
scim_group_idstringrequired
The legacy name for `directory_group_id`. Carries the same value.
directory_group_display_namestringrequired
The display name of the group, as reported by the identity provider.
scim_group_display_namestringrequired
The legacy name for `directory_group_display_name`. Carries the same value.
roleobjectoptional
precedenceintegerrequired
Mapping precedence, starting at 1. Lower values take priority when a user belongs to multiple mapped groups.
created_atintegerrequired
Unix timestamp (milliseconds) of when the mapping was created.
updated_atintegerrequired
Unix timestamp (milliseconds) of when the mapping was last updated.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
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 400 is returned: Request was not successful. 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.