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

Add roles to a role set

Adds one or more roles to an existing role set. You can optionally update the default role or creator role when adding new roles.

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

1 parameter · 3 body fields
role_set_key_or_idstringrequired
The key or ID of the role set
role_keysarray<string>required
Array of role keys to add to the role set. Must contain at least one role and no more than 10 roles.
default_role_keystringoptional
Optionally update the default role to one of the newly added roles.
creator_role_keystringoptional
Optionally update the creator role to one of the newly added roles.

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.