Role Sets

Create a role set

Changed on

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.

post/role_sets

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/role_sets
  • Auth: HTTP bearer

Request body

namestring required

The name of the new role set

keystring

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.

descriptionstring nullable

Optional description for the role set

default_role_keystring required

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_keystring required

The key of the role to assign to organization creators. Must be one of the roles in the roles array.

type'initial' | 'custom'

The type of the role set. "initial" role sets are the default for new organizations. Only one role set can be "initial" per instance.

rolesstring[] required

Array of role keys to include in the role set. Must contain at least one role and no more than 10 roles.

Response

Success

object'role_set' required
idstring required

The unique identifier of the role set

namestring required

The name of the role set

keystring required

A unique key for the role set (e.g., "role_set:default")

descriptionstring nullable required

Optional description of the role set

type'initial' | 'custom' required

The type of the role set ("initial" or "custom")

created_atinteger required

Unix timestamp of role set creation

updated_atinteger required

Unix timestamp of last role set update

Changes