Clerk

Clerk Organization Roles API

Manage custom roles in an organization.

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 /organization_roles List organization roles · Get a List of Organization Roles #
Ask an LLM
“What custom organization roles exist in my instance?”
“Can I search organization roles by name or key?”
Tell an agent
List all organization roles.
Find organization roles matching {query}.
POST /organization_roles Create an organization role · Create an Organization Role #
Ask an LLM
“How do I define a custom role like billing manager for organizations?”
“What format must an organization role key follow?”
Tell an agent
Create an organization role {name} with key {key}.
Create role {name} ({key}) with permissions {permissions}.
GET /organization_roles/{organization_role_id} Retrieve an organization role · Retrieve an Organization Role #
Ask an LLM
“How do I see the permissions attached to one organization role?”
“What details does a single organization role have?”
Tell an agent
Get organization role {organization_role_id}.
Show the permissions of role {organization_role_id}.
PATCH /organization_roles/{organization_role_id} Update an organization role · Update an Organization Role #
Ask an LLM
“How do I rename an organization role or change its description?”
“Can I replace a role's whole permission set at once?”
Tell an agent
Rename organization role {organization_role_id} to {name}.
Replace the permissions of role {organization_role_id} with {permissions}.
DELETE /organization_roles/{organization_role_id} Delete an organization role · Delete an Organization Role #
Ask an LLM
“How do I delete a custom organization role?”
“Why can't I delete a role that is still assigned to members?”
Tell an agent destructive · confirm first
Delete organization role {organization_role_id}.
Remove the unused role {organization_role_id} from the instance.
POST /organization_roles/{organization_role_id}/permissions/{permission_id} Add a permission to an organization role · Assign a Permission to an Organization Role #
Ask an LLM
“How do I grant one extra permission to an existing organization role?”
“Can I attach a single permission to a role without resending all of them?”
Tell an agent
Assign permission {permission_id} to role {organization_role_id}.
Give organization role {organization_role_id} the permission {permission_id}.
DELETE /organization_roles/{organization_role_id}/permissions/{permission_id} Remove a permission from an organization role · Remove a Permission from an Organization Role #
Ask an LLM
“How do I take a single permission away from an organization role?”
“Can I revoke one permission from a role and keep the others?”
Tell an agent destructive · confirm first
Remove permission {permission_id} from role {organization_role_id}.
Revoke the permission {permission_id} on organization role {organization_role_id}.

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-organization-roles-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-organization-roles-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-organization-roles-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Clerk Backend Organization Roles 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: Organization Roles
  description: Manage custom roles in an organization.
  externalDocs:
    url: https://clerk.com/docs/organizations/manage-member-roles
paths:
  /organization_roles:
    get:
      operationId: ListOrganizationRoles
      x-speakeasy-group: organizationRoles
      x-speakeasy-name-override: list
      summary: Get a List of Organization Roles
      description: 'This request returns the list of organization roles for the instance.

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

        The organization roles are ordered by descending creation date.

        Most recent roles will be returned first.'
      tags:
      - Organization Roles
      parameters:
      - in: query
        name: query
        description: 'Returns organization roles with ID, name, or key that match the given query.

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

          At the moment, you can order the returned organization roles 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 organization roles 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/Roles'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: CreateOrganizationRole
      x-speakeasy-group: organizationRoles
      x-speakeasy-name-override: create
      summary: Create an Organization Role
      description: '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.'
      tags:
      - Organization Roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the new organization role
                key:
                  type: string
                  description: A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores.
                description:
                  type:
                  - string
                  - 'null'
                  description: Optional description for the role
                permissions:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  description: Array of permission IDs to assign to the role
                include_in_initial_role_set:
                  type:
                  - boolean
                  - 'null'
                  description: Whether this role should be included in the initial role set
              additionalProperties: false
              required:
              - name
              - key
      responses:
        '200':
          $ref: '#/components/responses/Role'
        '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'
  /organization_roles/{organization_role_id}:
    get:
      operationId: GetOrganizationRole
      x-speakeasy-group: organizationRoles
      x-speakeasy-name-override: get
      summary: Retrieve an Organization Role
      description: Use this request to retrieve an existing organization role by its ID.
      tags:
      - Organization Roles
      parameters:
      - in: path
        required: true
        name: organization_role_id
        schema:
          type: string
        description: The ID of the organization role
      responses:
        '200':
          $ref: '#/components/responses/Role'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      operationId: UpdateOrganizationRole
      x-speakeasy-group: organizationRoles
      x-speakeasy-name-override: update
      summary: Update an Organization Role
      description: 'Updates an existing organization role.

        You can update the name, key, description, and permissions of the role.

        All parameters are optional - you can update only the fields you want to change.

        If the role is used as a creator role or domain default role, updating the key will cascade the update to the organization settings.'
      tags:
      - Organization Roles
      parameters:
      - in: path
        required: true
        name: organization_role_id
        schema:
          type: string
        description: The ID of the organization role to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type:
                  - string
                  - 'null'
                  description: The new name for the organization role
                key:
                  type:
                  - string
                  - 'null'
                  description: A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores.
                description:
                  type:
                  - string
                  - 'null'
                  description: Optional description for the role
                permissions:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  description: Array of permission IDs to assign to the role. If provided, this will replace the existing permissions.
      responses:
        '200':
          $ref: '#/components/responses/Role'
        '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'
    delete:
      operationId: DeleteOrganizationRole
      x-speakeasy-group: organizationRoles
      x-speakeasy-name-override: delete
      summary: Delete an Organization Role
      description: 'Deletes the organization role.

        The role cannot be deleted if it is currently used as the default creator role, domain default role, assigned to any members, or exists in any invitations.'
      tags:
      - Organization Roles
      parameters:
      - in: path
        required: true
        name: organization_role_id
        schema:
          type: string
        description: The ID of the organization role to delete
      responses:
        '200':
          $ref: '#/components/responses/DeletedObject'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organization_roles/{organization_role_id}/permissions/{permission_id}:
    post:
      operationId: AssignPermissionToOrganizationRole
      x-speakeasy-group: organizationRoles
      x-speakeasy-name-override: assignPermission
      summary: Assign a Permission to an Organization Role
      description: Assigns a permission to an organization role
      tags:
      - Organization Roles
      parameters:
      - in: path
        required: true
        name: organization_role_id
        schema:
          type: string
        description: The ID of the organization role
      - in: path
        required: true
        name: permission_id
        schema:
          type: string
        description: The ID of the permission to assign
      responses:
        '200':
          $ref: '#/components/responses/Role'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: RemovePermissionFromOrganizationRole
      x-speakeasy-group: organizationRoles
      x-speakeasy-name-override: removePermission
      summary: Remove a Permission from an Organization Role
      description: Removes a permission from an organization role
      tags:
      - Organization Roles
      parameters:
      - in: path
        required: true
        name: organization_role_id
        schema:
          type: string
        description: The ID of the organization role
      - in: path
        required: true
        name: permission_id
        schema:
          type: string
        description: The ID of the permission to remove
      responses:
        '200':
          $ref: '#/components/responses/Role'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    Role:
      type: object
      properties:
        object:
          type: string
          enum:
          - role
        id:
          type: string
        name:
          type: string
        key:
          type: string
        description:
          type:
          - string
          - 'null'
        is_creator_eligible:
          type: boolean
          description: Whether this role is eligible to be an organization creator role
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation.

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last update.

            '
      additionalProperties: false
      required:
      - object
      - id
      - name
      - key
      - description
      - is_creator_eligible
      - permissions
      - created_at
      - updated_at
    Roles:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        total_count:
          type: integer
          format: int64
          description: 'Total number of roles

            '
      required:
      - data
      - total_count
    Permission:
      type: object
      properties:
        object:
          type: string
          enum:
          - permission
        id:
          type: string
        name:
          type: string
        key:
          type: string
        description:
          type: string
        type:
          type: string
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation.

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last update.

            '
      required:
      - object
      - id
      - name
      - key
      - description
      - type
      - created_at
      - updated_at
    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
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Roles:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Roles'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Role:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Role'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  parameters:
    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
    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
  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