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: 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' 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 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 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' 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 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