Clerk

Clerk Role Sets API

Role sets define collections of roles that can be assigned to organization members. Each organization uses one role set to determine the available roles for its members. Role sets support default roles for new members and creator roles for organization founders.

GitHub OpenAPI
Business capability
Identity & Access Management BC-620.20

Operations 7

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /role_sets List role sets · Get a List of Role Sets #
Ask an LLM
“Which role sets exist in my instance?”
“Can I search role sets by name and change their sort order?”
Tell an agent
List all role sets.
Search role sets for {query}.
POST /role_sets Create a role set · Create a Role Set #
Ask an LLM
“How do I group organization roles into a new role set?”
“Does a role set need a default role and a creator role?”
Tell an agent
Create role set {name} with roles {roles}, default role {default_role_key} and creator role {creator_role_key}.
Create role set {name} keyed {key} with roles {roles}, default {default_role_key}, creator {creator_role_key}.
GET /role_sets/{role_set_key_or_id} Retrieve a role set · Retrieve a Role Set #
Ask an LLM
“How do I see which roles are in a role set?”
“Can I look up a role set by its key instead of its ID?”
Tell an agent
Show role set {role_set_key_or_id}.
List the roles inside role set {role_set_key_or_id}.
PATCH /role_sets/{role_set_key_or_id} Update a role set's settings · Update a Role Set #
Ask an LLM
“How do I rename a role set or change its description?”
“Can I change which role new organization members get by default?”
Tell an agent
Rename role set {role_set_key_or_id} to {name}.
Set the default role of role set {role_set_key_or_id} to {default_role_key}.
POST /role_sets/{role_set_key_or_id}/replace Replace a role set and migrate organizations · Replace a Role Set #
Ask an LLM
“How do I retire a role set and move its organizations to another one?”
“Can I map old roles to new roles when replacing a role set?”
Tell an agent destructive · confirm first
Replace role set {role_set_key_or_id} with {dest_role_set_key}.
Migrate organizations from role set {role_set_key_or_id} to {dest_role_set_key} using mappings {reassignment_mappings}.
POST /role_sets/{role_set_key_or_id}/roles Add roles to a role set · Add Roles to a Role Set #
Ask an LLM
“How do I add more roles to an existing role set?”
“Can I update the creator role at the same time as adding roles?”
Tell an agent
Add roles {role_keys} to role set {role_set_key_or_id}.
Add roles {role_keys} to role set {role_set_key_or_id} and make {creator_role_key} the creator role.
POST /role_sets/{role_set_key_or_id}/roles/replace Swap one role for another in a role set · Replace a Role in a Role Set #
Ask an LLM
“How do I remove a role from a role set and move its members to a different role?”
“Are members reassigned automatically when a role in a role set is replaced?”
Tell an agent destructive · confirm first
In role set {role_set_key_or_id}, replace role {role_key} with {to_role_key}.
Retire role {role_key} in role set {role_set_key_or_id} and move its members to {to_role_key}.

Documentation

📖
Documentation
https://clerk.com/docs/reference/backend-api
📖
APIReference
https://clerk.com/docs/reference/backend-api
📖
GettingStarted
https://clerk.com/docs/quickstarts/overview
📖
Authentication
https://clerk.com/docs/backend-requests/making/jwt-templates
📖
Documentation
https://clerk.com/docs
📖
Documentation
https://clerk.com/docs/webhooks/overview

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-role-sets-api-openapi.yml

Other Resources

🔗
SpectralRuleset
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/rules/clerk-rules.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/clerk-com:clerk-com-role-sets-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

clerk-com-role-sets-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Clerk Backend Role Sets API
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Platform Team
    url: https://clerk.com/support
  description: 'The Clerk REST Backend API, meant to be accessed by backend servers.


    ### Versions


    When the API changes in a way that isn''t compatible with older versions, a new version is released.

    Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see Clerk API Versions.


    Please see https://clerk.com/docs for more information.'
  version: '2025-11-10'
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
tags:
- name: Role Sets
  description: 'Role sets define collections of roles that can be assigned to organization members.

    Each organization uses one role set to determine the available roles for its members.

    Role sets support default roles for new members and creator roles for organization founders.'
  externalDocs:
    url: https://clerk.com/docs/organizations/manage-member-roles
paths:
  /role_sets:
    get:
      operationId: ListRoleSets
      x-speakeasy-group: roleSets
      x-speakeasy-name-override: list
      summary: Get a List of Role Sets
      description: 'Returns a list of role sets for the instance.

        Results can be paginated using the optional `limit` and `offset` query parameters.

        The role sets are ordered by descending creation date by default.'
      tags:
      - Role Sets
      parameters:
      - in: query
        name: query
        description: 'Returns role sets with ID, name, or key that match the given query.

          Uses exact match for role set ID and partial match for name and key.'
        required: false
        schema:
          type: string
      - in: query
        name: order_by
        description: 'Allows to return role sets in a particular order.

          At the moment, you can order the returned role sets by their `created_at`, `name`, or `key`.

          In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.

          For example, if you want role sets to be returned in descending order according to their `created_at` property, you can use `-created_at`.

          If you don''t use `+` or `-`, then `+` is implied.

          Defaults to `-created_at`.'
        required: false
        schema:
          type: string
          default: -created_at
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/RoleSets'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: CreateRoleSet
      x-speakeasy-group: roleSets
      x-speakeasy-name-override: create
      summary: Create a Role Set
      description: '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.'
      tags:
      - Role Sets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the new role set
                key:
                  type: string
                  description: '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.'
                description:
                  type:
                  - string
                  - 'null'
                  description: Optional description for the role set
                default_role_key:
                  type: string
                  description: '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_key:
                  type: string
                  description: 'The key of the role to assign to organization creators.

                    Must be one of the roles in the `roles` array.'
                type:
                  type: string
                  enum:
                  - initial
                  - custom
                  description: 'The type of the role set. "initial" role sets are the default for new organizations.

                    Only one role set can be "initial" per instance.'
                roles:
                  type: array
                  items:
                    type: string
                  description: 'Array of role keys to include in the role set.

                    Must contain at least one role and no more than 10 roles.'
              additionalProperties: false
              required:
              - name
              - default_role_key
              - creator_role_key
              - roles
      responses:
        '200':
          $ref: '#/components/responses/RoleSet'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /role_sets/{role_set_key_or_id}:
    get:
      operationId: GetRoleSet
      x-speakeasy-group: roleSets
      x-speakeasy-name-override: get
      summary: Retrieve a Role Set
      description: Retrieves an existing role set by its key or ID.
      tags:
      - Role Sets
      parameters:
      - in: path
        required: true
        name: role_set_key_or_id
        schema:
          type: string
        description: The key or ID of the role set
      responses:
        '200':
          $ref: '#/components/responses/RoleSet'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      operationId: UpdateRoleSet
      x-speakeasy-group: roleSets
      x-speakeasy-name-override: update
      summary: Update a Role Set
      description: 'Updates an existing role set.

        You can update the name, key, description, type, default role, or creator role.

        All parameters are optional - you can update only the fields you want to change.'
      tags:
      - Role Sets
      parameters:
      - in: path
        required: true
        name: role_set_key_or_id
        schema:
          type: string
        description: The key or ID of the role set to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type:
                  - string
                  - 'null'
                  description: The new name for the role set
                key:
                  type:
                  - string
                  - 'null'
                  description: A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores.
                description:
                  type:
                  - string
                  - 'null'
                  description: Optional description for the role set
                type:
                  type:
                  - string
                  - 'null'
                  enum:
                  - initial
                  description: 'Set to "initial" to make this the default role set for new organizations.

                    Only one role set can be "initial" per instance; setting this will change any existing initial role set to "custom".'
                default_role_key:
                  type:
                  - string
                  - 'null'
                  description: 'The key of the role to use as the default role for new organization members.

                    Must be an existing role in the role set.'
                creator_role_key:
                  type:
                  - string
                  - 'null'
                  description: 'The key of the role to assign to organization creators.

                    Must be an existing role in the role set.'
      responses:
        '200':
          $ref: '#/components/responses/RoleSet'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /role_sets/{role_set_key_or_id}/replace:
    post:
      operationId: ReplaceRoleSet
      x-speakeasy-group: roleSets
      x-speakeasy-name-override: replace
      summary: Replace a Role Set
      description: 'Replaces a role set with another role set. This is functionally equivalent to deleting

        the role set but allows for atomic replacement with migration support.

        Organizations using this role set will be migrated to the destination role set.'
      tags:
      - Role Sets
      parameters:
      - in: path
        required: true
        name: role_set_key_or_id
        schema:
          type: string
        description: The key or ID of the role set to replace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dest_role_set_key:
                  type: string
                  description: The key of the destination role set
                reassignment_mappings:
                  allOf:
                  - $ref: '#/components/schemas/ReassignmentMappings'
                  description: 'Mappings from source role keys to destination role keys.

                    Required if members have roles that need to be reassigned.'
              required:
              - dest_role_set_key
      responses:
        '200':
          $ref: '#/components/responses/DeletedObject'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /role_sets/{role_set_key_or_id}/roles:
    post:
      operationId: AddRolesToRoleSet
      x-speakeasy-group: roleSets
      x-speakeasy-name-override: addRoles
      summary: Add Roles to a Role Set
      description: 'Adds one or more roles to an existing role set.

        You can optionally update the default role or creator role when adding new roles.'
      tags:
      - Role Sets
      parameters:
      - in: path
        required: true
        name: role_set_key_or_id
        schema:
          type: string
        description: The key or ID of the role set
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role_keys:
                  type: array
                  items:
                    type: string
                  description: 'Array of role keys to add to the role set.

                    Must contain at least one role and no more than 10 roles.'
                default_role_key:
                  type: string
                  description: Optionally update the default role to one of the newly added roles.
                creator_role_key:
                  type: string
                  description: Optionally update the creator role to one of the newly added roles.
              required:
              - role_keys
      responses:
        '200':
          $ref: '#/components/responses/RoleSet'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /role_sets/{role_set_key_or_id}/roles/replace:
    post:
      operationId: ReplaceRoleInRoleSet
      x-speakeasy-group: roleSets
      x-speakeasy-name-override: replaceRole
      summary: Replace a Role in a Role Set
      description: 'Replaces a role in a role set with another role. This atomically removes

        the source role and reassigns any members to the destination role.'
      tags:
      - Role Sets
      parameters:
      - in: path
        required: true
        name: role_set_key_or_id
        schema:
          type: string
        description: The key or ID of the role set
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role_key:
                  type: string
                  description: The key of the role to remove from the role set
                to_role_key:
                  type: string
                  description: The key of the role to reassign members to
              required:
              - role_key
              - to_role_key
      responses:
        '200':
          $ref: '#/components/responses/RoleSet'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  responses:
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    RoleSet:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RoleSet'
    RoleSets:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RoleSets'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  schemas:
    RoleSetItem:
      type: object
      description: A role within a role set
      properties:
        object:
          type: string
          enum:
          - role_set_item
        id:
          type: string
          description: The unique identifier of the role
        name:
          type: string
          description: The name of the role
        key:
          type: string
          description: The key of the role (e.g., "org:admin", "org:member")
        description:
          type:
          - string
          - 'null'
          description: Optional description of the role
        members_count:
          type:
          - integer
          - 'null'
          format: int64
          description: The number of members assigned to this role within the role set
        has_members:
          type:
          - boolean
          - 'null'
          description: Whether this role has any members assigned within the role set
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of role creation
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last role update
      additionalProperties: false
      required:
      - object
      - id
      - name
      - key
      - description
      - created_at
      - updated_at
    RoleSets:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RoleSet'
        total_count:
          type: integer
          format: int64
          description: Total number of role sets
      required:
      - data
      - total_count
    DeletedObject:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
        id:
          type: string
        slug:
          type: string
        deleted:
          type: boolean
        external_id:
          type: string
      required:
      - object
      - deleted
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    ReassignmentMappings:
      type: object
      description: Mappings from source role keys to destination role keys for role reassignment
      additionalProperties:
        type: string
    RoleSet:
      type: object
      description: A role set defines a collection of roles that can be assigned to organization members
      properties:
        object:
          type: string
          enum:
          - role_set
        id:
          type: string
          description: The unique identifier of the role set
        name:
          type: string
          description: The name of the role set
        key:
          type: string
          description: A unique key for the role set (e.g., "role_set:default")
        description:
          type:
          - string
          - 'null'
          description: Optional description of the role set
        roles:
          type: array
          items:
            $ref: '#/components/schemas/RoleSetItem'
          description: The list of roles in this role set
        default_role:
          allOf:
          - $ref: '#/components/schemas/RoleSetItem'
          description: The default role assigned to new organization members
        creator_role:
          allOf:
          - $ref: '#/components/schemas/RoleSetItem'
          description: The role assigned to the creator of an organization
        type:
          type: string
          description: The type of the role set ("initial" or "custom")
          enum:
          - initial
          - custom
        role_set_migration:
          description: Active migration information, only present when status is "enqueued" or "in_progress"
          allOf:
          - $ref: '#/components/schemas/RoleSetMigration'
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of role set creation
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last role set update
      additionalProperties: false
      required:
      - object
      - id
      - name
      - key
      - description
      - roles
      - type
      - created_at
      - updated_at
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    RoleSetMigration:
      type: object
      description: Information about an ongoing role set migration
      properties:
        object:
          type: string
          enum:
          - role_set_migration
        id:
          type: string
          description: The unique identifier of the migration
        organization_id:
          type:
          - string
          - 'null'
          description: The organization ID if the migration is scoped to a specific organization
        instance_id:
          type: string
          description: The instance ID this migration belongs to
        source_role_set_id:
          type: string
          description: The ID of the source role set being migrated from
        dest_role_set_id:
          type:
          - string
          - 'null'
          description: The ID of the destination role set being migrated to
        trigger_type:
          type: string
          description: What triggered this migration (e.g., "role_set_deletion", "role_removal")
        status:
          type: string
          description: Current status of the migration (e.g., "enqueued", "in_progress", "completed")
        migrated_members:
          type: integer
          description: Number of members that have been migrated so far
        mappings:
          type:
          - object
          - 'null'
          description: Role key mappings from source to destination roles
          additionalProperties:
            type: string
        started_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp when the migration started
        completed_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp when the migration completed
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of migration creation
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last migration update
      additionalProperties: false
      required:
      - object
      - id
      - instance_id
      - source_role_set_id
      - trigger_type
      - status
      - migrated_members
      - created_at
      - updated_at
  parameters:
    LimitParameter:
      name: limit
      in: query
      description: 'Applies a limit to the number of results returned.

        Can be used for paginating the results together with `offset`.'
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
    OffsetParameter:
      name: offset
      in: query
      description: 'Skip the first `offset` results when paginating.

        Needs to be an integer greater or equal to zero.

        To be used in conjunction with `limit`.'
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key, obtained under "API Keys" in the Clerk Dashboard.
      bearerFormat: sk_<environment>_<secret value>
externalDocs:
  url: https://clerk.com/docs
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true