Clerk API (unofficial showcase)
PATCH/organization_roles/{organization_role_id}

Update an organization role

Updates an existing organization role. You can update the name, key, description, and permissions of the role. All parameters are optional - you can update only the fields you want to change. If the role is used as a creator role or domain default role, updating the key will cascade the update to the organization settings.

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

1 parameter · 4 body fields
organization_role_idstringrequired
The ID of the organization role to update
namestringoptional
The new name for the organization role
keystringoptional
A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores.
descriptionstringoptional
Optional description for the role
permissionsarray<string>optional
Array of permission IDs to assign to the role. If provided, this will replace the existing permissions.

6 status codes
200Success
objectstringrequired
Allowed:role
idstringrequired
namestringrequired
keystringrequired
descriptionstringrequired
is_creator_eligiblebooleanrequired
Whether this role is eligible to be an organization creator role
permissionsarray<object>required
created_atintegerrequired
Unix timestamp of creation.
updated_atintegerrequired
Unix timestamp of last update.
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.