Clerk API (unofficial showcase)
POST/role_sets

Create a role set

Creates a new role set with the given name and roles. The key must be unique for the instance and start with the 'role_set:' prefix, followed by lowercase alphanumeric characters and underscores only. You must provide at least one role and specify a default role key and creator role key.

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

7 body fields
namestringrequired
The name of the new role set
keystringoptional
A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores. If not provided, a key will be generated from the name.
descriptionstringoptional
Optional description for the role set
default_role_keystringrequired
The key of the role to use as the default role for new organization members. Must be one of the roles in the `roles` array.
creator_role_keystringrequired
The key of the role to assign to organization creators. Must be one of the roles in the `roles` array.
typestringoptional
The type of the role set. "initial" role sets are the default for new organizations. Only one role set can be "initial" per instance.
Allowed:initialcustom
rolesarray<string>required
Array of role keys to include in the role set. Must contain at least one role and no more than 10 roles.

7 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
402Payment required
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 402 is returned: Payment required. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.