Clerk API (unofficial showcase)
PATCH/role_sets/{role_set_key_or_id}

Update a role set

Updates an existing role set. You can update the name, key, description, type, default role, or creator role. All parameters are optional - you can update only the fields you want to change.

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

1 parameter · 6 body fields
role_set_key_or_idstringrequired
The key or ID of the role set to update
namestringoptional
The new name for the role set
keystringoptional
A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores.
descriptionstringoptional
Optional description for the role set
typestringoptional
Set to "initial" to make this the default role set for new organizations. Only one role set can be "initial" per instance; setting this will change any existing initial role set to "custom".
Allowed:initial
default_role_keystringoptional
The key of the role to use as the default role for new organization members. Must be an existing role in the role set.
creator_role_keystringoptional
The key of the role to assign to organization creators. Must be an existing role in the role set.

6 status codes
200Success
objectstringrequired
Allowed:role_set
idstringrequired
The unique identifier of the role set
namestringrequired
The name of the role set
keystringrequired
A unique key for the role set (e.g., "role_set:default")
descriptionstringrequired
Optional description of the role set
rolesarray<object>required
The list of roles in this role set
default_roleobjectoptional
The default role assigned to new organization members
creator_roleobjectoptional
The role assigned to the creator of an organization
typestringrequired
The type of the role set ("initial" or "custom")
Allowed:initialcustom
role_set_migrationobjectoptional
Active migration information, only present when status is "enqueued" or "in_progress"
created_atintegerrequired
Unix timestamp of role set creation
updated_atintegerrequired
Unix timestamp of last role set 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.