ClickHouse

ClickHouse API keys API

The API keys API from ClickHouse — 2 operation(s) for api keys.

GitHub OpenAPI

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}/keys List an organization's API keys · Get list of all keys #
Ask an LLM
“Which API keys exist in my ClickHouse Cloud organization?”
“Can I see every key our org has issued so I can audit them?”
Tell an agent
List all API keys in organization {org}.
Show me every key issued for org {org} so I can review who has access.
POST /v1/organizations/{organizationId}/keys Create a new API key · Create key #
Ask an LLM
“How do I generate a new API key for automation?”
“Can I make a key that expires on a set date and only works from certain IPs?”
Tell an agent
Create an API key named {name} in organization {org}.
Issue a new key {name} in org {org} that expires at {expireAt} and is limited to IP access list {ipAccessList}.
GET /v1/organizations/{organizationId}/keys/{keyId} Get details of one API key · Get key details #
Ask an LLM
“What roles and expiry does a specific API key have?”
“Is a particular key still enabled or has it been disabled?”
Tell an agent
Show the details of API key {keyId} in org {org}.
Look up the state and expiry date of key {keyId} in organization {org}.
PATCH /v1/organizations/{organizationId}/keys/{keyId} Update an existing API key · Update key #
Ask an LLM
“How do I disable an existing API key without deleting it?”
“Can I change the roles or IP allow list on a key I already created?”
Tell an agent
Set the state of key {keyId} in org {org} to {state}.
Rename existing key {keyId} in organization {org} to {name} and extend its expiry to {expireAt}.
DELETE /v1/organizations/{organizationId}/keys/{keyId} Delete an API key · Delete key #
Ask an LLM
“How do I permanently remove an API key we no longer use?”
“Can I delete the very key I'm using to make the request?”
Tell an agent destructive · confirm first
Delete API key {keyId} from organization {org}.
Permanently remove the leaked key {keyId} in org {org}.

Documentation

📖
Documentation
https://clickhouse.com/docs/cloud/manage/api/api-overview
📖
APIReference
https://clickhouse.com/docs/products/cloud/api-reference/organization/get-list-of-available-organizations

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clickhouse/refs/heads/main/openapi/clickhouse-api-keys-api-openapi.yml

Other Resources

🔗
ToolCrosswalk
https://raw.githubusercontent.com/api-evangelist/clickhouse/refs/heads/main/mcp/clickhouse-tool-crosswalk.yml
🔗
Swagger
https://clickhouse.com/docs/cloud/manage/api/swagger

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-api-keys-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

clickhouse-api-keys-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: OpenAPI spec for ClickHouse Cloud API keys 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: API Keys
paths:
  /v1/organizations/{organizationId}/keys:
    get:
      summary: Get list of all keys
      description: Returns a list of all keys in the organization.
      operationId: openapiKeyGetList
      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/ApiKey'
        '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:
      - API Keys
    post:
      summary: Create key
      description: Creates new API key.
      operationId: openapiKeyCreate
      parameters:
      - in: path
        name: organizationId
        description: ID of the organization that will own the key.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyPostRequest'
      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/ApiKeyPostResponse'
        '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:
      - API Keys
  /v1/organizations/{organizationId}/keys/{keyId}:
    get:
      summary: Get key details
      description: Returns a single key details.
      operationId: openapiKeyGet
      parameters:
      - in: path
        name: organizationId
        description: ID of the requested organization.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: keyId
        description: ID of the requested key.
        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/ApiKey'
        '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:
      - API Keys
    patch:
      summary: Update key
      description: Updates API key properties.
      operationId: openapiKeyUpdate
      parameters:
      - in: path
        name: organizationId
        description: ID of the organization that owns the key.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: keyId
        description: ID of the key to update.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyPatchRequest'
      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/ApiKey'
        '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:
      - API Keys
    delete:
      summary: Delete key
      description: Deletes API key. Only a key not used to authenticate the active request can be deleted.
      operationId: openapiKeyDelete
      parameters:
      - in: path
        name: organizationId
        description: ID of the organization that owns the key.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: keyId
        description: ID of the key to delete.
        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:
      - API Keys
components:
  schemas:
    ApiKey:
      properties:
        id:
          description: Unique API key ID.
          type: string
          format: uuid
        name:
          description: Name of the key
          type: string
        state:
          description: 'State of the key: ''enabled'', ''disabled''.'
          type: string
          enum:
          - enabled
          - disabled
        roles:
          type: array
          description: DEPRECATED. Use `assignedRoles` instead. List of roles assigned to the key. For organizations that have migrated to custom roles, this field is frozen at the pre-migration value and does not reflect current role assignments.
          items:
            type: string
            enum:
            - admin
            - developer
            - query_endpoints
          deprecated: true
        assignedRoles:
          type: array
          description: Custom roles and System roles assigned to this API key
          items:
            $ref: '#/components/schemas/AssignedRole'
        keySuffix:
          description: Last 4 letters of the key.
          type: string
        createdAt:
          description: Timestamp the key was created. ISO-8601.
          type: string
          format: date-time
        expireAt:
          description: Timestamp the key expires. If not present, `null` or is empty the key never expires. ISO-8601.
          type:
          - string
          - 'null'
          format: date-time
        usedAt:
          description: Timestamp the key was used last time, with one-minute precision. If not present the key was never used. ISO-8601.
          type: string
          format: date-time
        ipAccessList:
          type: array
          description: List of IP addresses allowed to access the API using this key
          items:
            $ref: '#/components/schemas/IpAccessListEntry'
    ApiKeyPatchRequest:
      properties:
        name:
          description: Name of the key
          type: string
        roles:
          type: array
          description: DEPRECATED. Use `assignedRoleIds` instead. List of roles assigned to the key.
          items:
            type: string
            enum:
            - admin
            - developer
            - query_endpoints
          deprecated: true
        assignedRoleIds:
          type: array
          description: Array of role UUIDs to assign to the API key
          items:
            type: string
            format: uuid
        expireAt:
          description: Timestamp the key expires. If `null` or is empty the key never expires. ISO-8601.
          type:
          - string
          - 'null'
          format: date-time
        state:
          description: 'State of the key: ''enabled'', ''disabled''.'
          type: string
          enum:
          - enabled
          - disabled
        ipAccessList:
          type: array
          description: List of IP addresses allowed to access the API using this key
          items:
            $ref: '#/components/schemas/IpAccessListEntry'
    ApiKeyPostResponse:
      properties:
        key:
          $ref: '#/components/schemas/ApiKey'
        keyId:
          description: Generated key ID. Provided only if there was no 'hashData' in the request.
          type: string
        keySecret:
          description: Generated key secret. Provided only if there was no 'hashData' in the request.
          type: string
    AssignedRole:
      properties:
        roleId:
          description: Unique identifier of the role
          type: string
          format: uuid
        roleName:
          description: Human-readable name of the role
          type: string
        roleType:
          description: 'Type of role: system (predefined) or custom (organization-defined)'
          type: string
          enum:
          - system
          - custom
    ApiKeyHashData:
      properties:
        keyIdHash:
          description: 'Hash of the key ID. '
          type: string
        keyIdSuffix:
          description: 'Last 4 digits of the key ID. Algorithm: echo -n "yourpassword" | sha256sum | tr -d ''-'' | xxd -r -p | base64'
          type: string
        keySecretHash:
          description: 'Hash of the key secret. Algorithm: echo -n "yourpassword" | sha256sum | tr -d ''-'' | xxd -r -p | base64'
          type: string
    ApiKeyPostRequest:
      properties:
        name:
          description: Name of the key.
          type: string
        expireAt:
          description: Timestamp the key expires. If not present, `null` or is empty the key never expires. ISO-8601.
          type:
          - string
          - 'null'
          format: date-time
        state:
          description: 'Initial state of the key: ''enabled'', ''disabled''. If not provided the new key will be ''enabled''.'
          type: string
          enum:
          - enabled
          - disabled
        hashData:
          $ref: '#/components/schemas/ApiKeyHashData'
        roles:
          type: array
          description: DEPRECATED. Use `assignedRoleIds` instead. List of roles assigned to the key. Contains at least 1 element.
          items:
            type: string
            enum:
            - admin
            - developer
            - query_endpoints
          deprecated: true
        assignedRoleIds:
          type: array
          description: Array of role UUIDs to assign to the API key
          items:
            type: string
            format: uuid
        ipAccessList:
          type: array
          description: List of IP addresses allowed to access the API using this key
          items:
            $ref: '#/components/schemas/IpAccessListEntry'
    IpAccessListEntry:
      properties:
        source:
          description: IP or CIDR
          type: string
        description:
          description: Optional description of IPv4 address or IPv4 CIDR to allow access from
          type: string
  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