Clerk API (unofficial showcase)
POST/role_sets/{role_set_key_or_id}/roles/replace

Replace a role in a role set

Replaces a role in a role set with another role. This atomically removes the source role and reassigns any members to the destination role.

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

1 parameter · 2 body fields
role_set_key_or_idstringrequired
The key or ID of the role set
role_keystringrequired
The key of the role to remove from the role set
to_role_keystringrequired
The key of the role to reassign members to

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.