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