openapi: 3.1.0
info:
  title: TiDB Cloud API Keys API
  description: The TiDB Cloud API is a REST interface that provides programmatic access to manage administrative objects within TiDB Cloud. It supports managing projects, clusters, backups, restores, data imports, billing, and private endpoint connections across both TiDB Cloud Serverless and TiDB Cloud Dedicated tiers. The API uses HTTP Digest Authentication with public and private API keys and returns JSON-formatted responses. Available as both v1beta and the newer v1beta1 versions, it enables automation of database infrastructure lifecycle management at scale.
  version: v1beta1
  contact:
    name: TiDB Cloud Support
    url: https://docs.pingcap.com/tidbcloud/api-overview/
  termsOfService: https://www.pingcap.com/legal/privacy-policy/
servers:
- url: https://dedicated.tidbapi.com/v1beta1
  description: Dedicated Cluster API Server
- url: https://iam.tidbapi.com/v1beta1
  description: IAM API Server
- url: https://billing.tidbapi.com/v1beta1
  description: Billing API Server
security:
- digestAuth: []
tags:
- name: API Keys
  description: Operations for creating, listing, updating, and deleting TiDB Cloud API keys.
paths:
  /apikeys:
    get:
      operationId: listApiKeys
      summary: List API keys
      description: Returns a paginated list of API keys for the organization or a specific project. Each key entry includes its display name, access key, role, and creation time. Secret keys are not returned after initial creation.
      tags:
      - API Keys
      parameters:
      - name: projectId
        in: query
        description: Filter API keys by project ID. Omit for organization-level keys.
        required: false
        schema:
          type: integer
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: A paginated list of API keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListApiKeysResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createApiKey
      summary: Create an API key
      description: Creates a new API key with the specified display name, project scope, and role. The response includes both the public access key and the private secret key. The secret key is only returned at creation time and cannot be retrieved afterwards; store it securely.
      tags:
      - API Keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '200':
          description: API key created successfully. Save the secret key now as it will not be shown again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apikeys/{accessKey}:
    get:
      operationId: getApiKey
      summary: Get an API key
      description: Returns the metadata and permissions for a specific API key identified by its public access key. The private secret key is not returned.
      tags:
      - API Keys
      parameters:
      - $ref: '#/components/parameters/accessKey'
      responses:
        '200':
          description: API key details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateApiKey
      summary: Update an API key
      description: Updates the display name or role of an existing API key. Only the fields provided in the request body are modified. The access key and secret key remain unchanged.
      tags:
      - API Keys
      parameters:
      - $ref: '#/components/parameters/accessKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiKeyRequest'
      responses:
        '200':
          description: API key updated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteApiKey
      summary: Delete an API key
      description: Permanently deletes an API key. Once deleted, any requests authenticated with this key will be rejected. This action cannot be undone.
      tags:
      - API Keys
      parameters:
      - $ref: '#/components/parameters/accessKey'
      responses:
        '200':
          description: API key deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    accessKey:
      name: accessKey
      in: path
      description: The public access key portion of the API key pair.
      required: true
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      description: Maximum number of results to return per page. Default is 100, maximum is 100.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
    pageToken:
      name: pageToken
      in: query
      description: Pagination token returned from a previous list request to retrieve the next page.
      required: false
      schema:
        type: string
  schemas:
    ListApiKeysResponse:
      type: object
      description: Paginated list of API keys.
      properties:
        apiKeys:
          type: array
          description: The list of API key objects.
          items:
            $ref: '#/components/schemas/ApiKey'
        nextPageToken:
          type: string
          description: Token to retrieve the next page of results.
    CreateApiKeyRequest:
      type: object
      description: Request body for creating a new TiDB Cloud API key.
      required:
      - displayName
      - role
      properties:
        displayName:
          type: string
          description: The display name for the new API key.
        projectId:
          type: integer
          description: The project ID to scope the API key to. Use 0 for an organization-level key.
        role:
          type: string
          description: The role to assign to the API key.
    ApiKey:
      type: object
      description: A TiDB Cloud API key used for authenticating API requests.
      properties:
        name:
          type: string
          description: The resource name of the API key.
        accessKey:
          type: string
          description: The public access key used as the username in Digest Authentication.
        secretKey:
          type: string
          description: The private secret key used as the password. Only returned at creation time.
        displayName:
          type: string
          description: The human-readable display name for the API key.
        role:
          type: string
          description: The role assigned to the API key (e.g., Organization Owner, Project Viewer).
    ErrorResponse:
      type: object
      description: Standard error response returned when an API request fails.
      properties:
        code:
          type: integer
          description: The HTTP status code of the error.
        status:
          type: string
          description: The error status string.
        error:
          type: string
          description: A machine-readable error code identifier.
        msgPrefix:
          type: string
          description: A human-readable error message describing the failure.
    UpdateApiKeyRequest:
      type: object
      description: Request body for updating an existing API key.
      properties:
        displayName:
          type: string
          description: The new display name for the API key.
        role:
          type: string
          description: The new role for the API key.
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed. Check your API key credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    digestAuth:
      type: http
      scheme: digest
      description: HTTP Digest Authentication using a TiDB Cloud API public key as the username and private key as the password. Keys are generated in the TiDB Cloud console under Organization Settings > API Keys.
externalDocs:
  description: TiDB Cloud API Overview
  url: https://docs.pingcap.com/tidbcloud/api-overview/