ClickHouse Role Management API

The Role Management API from ClickHouse — 2 operation(s) for role management.

Documentation GitHub OpenAPI

Business capability

Operations 5

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 /v1/organizations/{organizationId}/roles List the organization's roles · List all available roles for an organization #

Ask an LLM

“Which system and custom roles are available in my ClickHouse Cloud organization?”

“What roles can I assign to members and API keys?”

Tell an agent

List all roles in organization {org}.

Show both system and custom roles defined for org {org}.

POST /v1/organizations/{organizationId}/roles Create a custom organization role · Create a new role #

Ask an LLM

“How do I create a custom role with its own permission policies?”

“Can I assign actors to a new role at the moment I create it?”

Tell an agent

Create a role named {name} in org {org} with policies {policies} and actors {actors}.

Add a new custom role {name} to organization {org} granting {policies} to {actors}.

GET /v1/organizations/{organizationId}/roles/{roleId} Get a role's policies and actors · Get role details #

Ask an LLM

“What permissions does a particular role grant?”

“Who is assigned to a given role?”

Tell an agent

Show role {roleId} in organization {org}.

List the policies and actors on role {roleId} in org {org}.

PATCH /v1/organizations/{organizationId}/roles/{roleId} Update a custom organization role · Update a role #

Ask an LLM

“How do I add or remove actors from an existing custom role?”

“Can I change only a role's policies and leave its name alone?”

Tell an agent

Rename custom role {roleId} in org {org} to {name}.

Set the actors on existing role {roleId} in organization {org} to {actors}.

DELETE /v1/organizations/{organizationId}/roles/{roleId} Delete a custom organization role · Delete a role #

Ask an LLM

“How do I delete a custom role and all its policies?”

“Can system roles be deleted?”

Tell an agent destructive · confirm first

Delete custom role {roleId} from organization {org}.

Remove role {roleId} and its policies in org {org}.

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/clickhouse:clickhouse-role-management-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

openapi: 3.2.0
info:
  title: OpenAPI spec for ClickHouse Cloud Role Management API
  version: '1.0'
  contact:
    name: ClickHouse Support
    url: https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1107336
    email: support@clickhouse.com
servers:
- url: https://api.clickhouse.cloud
security:
- basicAuth: []
tags:
- name: Role Management
paths:
  /v1/organizations/{organizationId}/roles:
    get:
      summary: List all available roles for an organization
      description: Returns all available roles (system + custom) for an organization.
      operationId: organizationRolesGetList
      parameters:
      - in: path
        name: organizationId
        description: ID of the requested organization.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 200
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/RBACRole'
        '400':
          description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 400
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '500':
          description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code.
                    example: 500
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
      tags:
      - Role Management
    post:
      summary: Create a new role
      description: Creates a new custom role for an organization with specified policies and actors.
      operationId: organizationRolePost
      parameters:
      - in: path
        name: organizationId
        description: ID of the requested organization.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleCreateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 200
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
                  result:
                    $ref: '#/components/schemas/RBACRole'
        '400':
          description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 400
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '500':
          description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code.
                    example: 500
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
      tags:
      - Role Management
  /v1/organizations/{organizationId}/roles/{roleId}:
    get:
      summary: Get role details
      description: Returns details for a specific role.
      operationId: organizationRoleGet
      parameters:
      - in: path
        name: organizationId
        description: ID of the requested organization.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: roleId
        description: ID of the requested role.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 200
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
                  result:
                    $ref: '#/components/schemas/RBACRole'
        '400':
          description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 400
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '500':
          description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code.
                    example: 500
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
      tags:
      - Role Management
    patch:
      summary: Update a role
      description: Updates an existing custom role. System roles cannot be updated. All fields are optional - only provided fields will be updated.
      operationId: organizationRolePatch
      parameters:
      - in: path
        name: organizationId
        description: ID of the requested organization.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: roleId
        description: ID of the requested role.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleUpdateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 200
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
                  result:
                    $ref: '#/components/schemas/RBACRole'
        '400':
          description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 400
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '500':
          description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code.
                    example: 500
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
      tags:
      - Role Management
    delete:
      summary: Delete a role
      description: Deletes an existing custom role. System roles cannot be deleted. This operation will remove the role and all its associated policies.
      operationId: organizationRoleDelete
      parameters:
      - in: path
        name: organizationId
        description: ID of the requested organization.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: roleId
        description: ID of the requested role.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 200
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '400':
          description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 400
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '500':
          description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code.
                    example: 500
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
      tags:
      - Role Management
components:
  schemas:
    RoleUpdateRequest:
      properties:
        name:
          description: New name for the role
          type: string
        actors:
          type: array
          description: New list of actor resource IDs (replaces existing actors)
          items:
            type: string
        policies:
          type: array
          description: New list of policies (replaces existing policies)
          items:
            $ref: '#/components/schemas/RBACPolicyCreateRequest'
    RBACPolicyTags:
      properties:
        grants:
          type: array
          description: Optional list of database grants (e.g., database names)
          items:
            type: string
        roleV2:
          description: Optional SQL console role type
          type: string
          enum:
          - sql-console-readonly
          - sql-console-admin
    RBACPolicyCreateRequest:
      properties:
        allowDeny:
          description: Whether this policy allows or denies access
          type: string
          enum:
          - ALLOW
          - DENY
        permissions:
          type: array
          description: List of permissions to grant or deny (e.g., ["control-plane:organization:view"])
          items:
            type: string
        resources:
          type: array
          description: List of resource IDs this policy applies to (e.g., ["instance/uuid", "instance/*"])
          items:
            type: string
        tags:
          $ref: '#/components/schemas/RBACPolicyTags'
      required:
      - allowDeny
      - permissions
      - resources
    RoleCreateRequest:
      properties:
        name:
          description: Name of the role
          type: string
        actors:
          type: array
          description: List of actor resource IDs to assign to this role (e.g., ["user/uuid", "apiKey/uuid"])
          items:
            type: string
        policies:
          type: array
          description: List of policies to create for this role
          items:
            $ref: '#/components/schemas/RBACPolicyCreateRequest'
      required:
      - name
      - actors
      - policies
    RBACPolicy:
      properties:
        id:
          description: Unique policy identifier
          type: string
        roleId:
          description: ID of the role this policy belongs to
          type: string
        tenantId:
          description: Tenant resource ID (e.g., organization/uuid)
          type: string
        allowDeny:
          description: Whether this policy allows or denies access
          type: string
          enum:
          - ALLOW
          - DENY
        permissions:
          type: array
          description: List of permissions granted or denied by this policy
          items:
            type: string
        resources:
          type: array
          description: List of resource IDs this policy applies to (e.g., instance/uuid, instance/*)
          items:
            type: string
        tags:
          $ref: '#/components/schemas/RBACPolicyTags'
    RBACRole:
      properties:
        id:
          description: Unique role identifier
          type: string
        tenantId:
          description: Tenant resource ID (e.g., organization/uuid)
          type: string
        ownerId:
          description: Owner resource ID (e.g., organization/uuid)
          type: string
        name:
          description: Name of the role
          type: string
        type:
          description: Whether this is a system role or a custom role
          type: string
          enum:
          - system
          - custom
        actors:
          type: array
          description: List of actor resource IDs assigned to this role (e.g., user/uuid, apiKey/uuid)
          items:
            type: string
        policies:
          type: array
          description: List of policies associated with this role
          items:
            $ref: '#/components/schemas/RBACPolicy'
        createdAt:
          description: Timestamp when the role was created. ISO-8601.
          type: string
          format: date-time
        updatedAt:
          description: Timestamp when the role was last updated. ISO-8601.
          type: string
          format: date-time
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi'
x-tagGroups:
- name: Organization
  tags:
  - Organization
  - Billing
  - User management
  - Role Management
  - UDF
- name: Service
  tags:
  - Service
  - Backup
- name: API keys
  tags:
  - API keys
- name: Prometheus
  tags:
  - Prometheus
- name: ClickPipes
  tags:
  - ClickPipes
- name: ClickStack
  tags:
  - ClickStack
- name: Postgres
  tags:
  - Postgres

ClickHouse Role Management API

Operations 5

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification