Clerk API (unofficial showcase)
POST/organization_roles

Create an organization role

Creates a new organization role with the given name and permissions for an instance. The key must be unique for the instance and start with the 'org:' prefix, followed by lowercase alphanumeric characters and underscores only. You can optionally provide a description for the role and specify whether it should be included in the initial role set. Organization roles support permissions that can be assigned to control access within the organization.

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

5 body fields
namestringrequired
The name of the new organization role
keystringrequired
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
include_in_initial_role_setbooleanoptional
Whether this role should be included in the initial role set

7 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
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.