PingCAP Data API Key API

openapi: 3.2.0
info:
  title: TiDB Cloud Data Service OPEN Data API Key API
  description: '# Overview


    The TiDB Cloud Data Service API provides a RESTful interface for programmatically managing administrative objects within the TiDB Cloud Data Service.'
  version: v1beta1
servers:
- url: https://dataservice.tidbapi.com
tags:
- name: Data API Key
  description: Create, get, update, delete, and list Data API keys of a Data App. The Data API key in Data Service is different from the key used in the TiDB Cloud API. The Data API key is used to access data in the TiDB Cloud clusters, whereas the TiDB Cloud API key is used to manage resources such as projects, clusters, Data Apps, and endpoints.
paths:
  /v1beta1/dataApps/{dataAppId}/apiKeys:
    get:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/apiKeys?pageSize=5'"
      summary: List all API keys for a Data App
      operationId: APIKey_ListApiKeys
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ListApiKeysResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      - name: pageSize
        description: The maximum number of items to return. If it is not set or set to `0`, the default value `100` will be used.
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 100
          minimum: 1
      - name: pageToken
        description: The identifier of the current page, used to retrieve the next page of results. You can get this value from the `nextPageToken` field in the previous response. To access the first page of data, omit this field.
        in: query
        required: false
        schema:
          type: string
      tags:
      - Data API Key
    post:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request POST \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/apiKeys' \\\n  --header 'Content-Type: application/json' \\\n  --data-raw '{\n    \"description\": \"A new API Key.\",\n    \"role\": \"READ_AND_WRITE\",\n    \"rateLimitRpm\": 100\n  }'"
      summary: Create an API key for a Data App
      description: For each Data App, you can create up to **100** API keys.
      operationId: APIKey_CreateApiKey
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ApiKey'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data API Key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1beta1ApiKey'
        description: Data API Key
        required: true
  /v1beta1/dataApps/{dataAppId}/apiKeys/{apiKeyId}:
    patch:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request PATCH \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/apiKeys/{apiKeyId}' \\\n  --header 'Content-Type: application/json' \\\n  --data-raw '{\n    \"description\": \"Update a API Key.\",\n    \"role\": \"READ_AND_WRITE\",\n    \"rateLimitRpm\": 50\n  }'"
      summary: Update an API key for a Data App
      description: 'With this endpoint, you can update the description, role, rate limit, or expiration time of an API key.


        **Note:** You cannot update an expired key.'
      operationId: APIKey_UpdateApiKey
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ApiKey'
        default:
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      - name: apiKeyId
        description: The ID of the API key, which is returned when you [create an API key](#tag/Data-API-Key/operation/APIKey_CreateApiKey).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data API Key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1beta1ApiKey'
        description: Data API Key
        required: true
    get:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/apiKeys/{apiKeyId}'"
      summary: Get an API key by ID
      operationId: APIKey_GetApiKey
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ApiKey'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      - name: apiKeyId
        description: The ID of the API key, which is returned when you [Create an API key](#tag/Data-API-Key/operation/APIKey_CreateApiKey).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data API Key
    delete:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request DELETE \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/apiKeys/{apiKeyId}'"
      summary: Delete an API key for a Data App
      description: Before you delete an API key, make sure that the API key is not used by any Data App.
      operationId: APIKey_DeleteApiKey
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      - name: apiKeyId
        description: The ID of the API key, which is returned when you [Create an API key](#tag/Data-API-Key/operation/APIKey_CreateApiKey).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data API Key
components:
  schemas:
    v1beta1ApiKeyRes:
      type: object
      properties:
        apiKeyId:
          type: string
          format: uint64
          description: The ID of the API key.
        name:
          type: string
          description: The unique identifier for the API key, which is generated by the API and follows the format `dataApps/{dataAppId}/apiKeys/{apiKey}`.
        publicKey:
          type: string
          description: The public key for the API key.
        privateKey:
          type: string
          description: The private key for the API key. This is only fully displayed when the key is initially created. For security reasons, subsequent requests will obscure most of the key, revealing only the last four characters.
        description:
          type: string
          description: The description of the API key.
        role:
          $ref: '#/components/schemas/ApiKeyRole'
          description: The role of the API key.
        rateLimitRpm:
          type: integer
          format: int32
          description: The maximum number of API requests allowed per minute using this key.
        expireState:
          $ref: '#/components/schemas/ApiKeyExpireState'
          description: Expire state of the API Key
        expireTime:
          type: string
          description: 'The time at which the API key will expire. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
        apiKeyExpireSetting:
          $ref: '#/components/schemas/ApiKeyApiKeyExpireSetting'
          description: The expiration settings for the API key.
      description: An API key of a Data App
    ApiKeyRole:
      type: string
      enum:
      - READ_AND_WRITE
      - READ_ONLY
      default: READ_ONLY
      description: "Controls whether the API key can read or write data to the clusters linked to the Data App.\n- `READ_AND_WRITE`: allows the API key to read and write data. You can use this API key to execute all SQL statements, such as DML and DDL statements.\n - `READ_ONLY`:  only allows the API key to read data, such as `SELECT`, `SHOW`, `USE`, `DESC`, and `EXPLAIN` statements."
    ApiKeyExpireOption:
      type: string
      enum:
      - EXPIRE_OPTION_NEVER_EXPIRE
      - EXPIRE_OPTION_SET_TTL
      default: EXPIRE_OPTION_NEVER_EXPIRE
      description: "The method used to determine the API key's expiration:\n- `EXPIRE_OPTION_NEVER_EXPIRE`: this key will never expire\n - `EXPIRE_OPTION_SET_TTL`: this key will expire after the time specified by `apikeyTtl`"
    ApiKeyExpireState:
      type: string
      enum:
      - EXPIRE_STATE_NEVER_EXPIRE
      - EXPIRE_STATE_EXPIRED
      - EXPIRE_STATE_NOT_EXPIRE
      default: EXPIRE_STATE_NEVER_EXPIRE
      description: "The expiration state of the API key:\n- `EXPIRE_STATE_NEVER_EXPIRE`: this API key never expires\n - `EXPIRE_STATE_EXPIRED`: this API key has expired\n - `EXPIRE_STATE_NOT_EXPIRE`: this API key is currently active"
    ApiKeyApiKeyExpireSetting:
      type: object
      properties:
        expireOption:
          $ref: '#/components/schemas/ApiKeyExpireOption'
          default: EXPIRE_OPTION_NEVER_EXPIRE
        apiKeyTtl:
          type: integer
          format: int64
          description: 'The expiration time for the key, in minutes.

            The filed is only available when `expireOption` is set to `EXPIRE_OPTION_SET_TTL`.'
          minimum: 1
          maximum: 525600
      description: The expiration settings for the API key.
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    v1beta1ListApiKeysResponse:
      type: object
      properties:
        apiKeys:
          type: array
          items:
            $ref: '#/components/schemas/v1beta1ApiKeyRes'
          description: The items of API keys in the Data App.
        nextPageToken:
          type: string
          description: The token to retrieve the next page of results.
      title: Response for ListApiKeys
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    v1beta1ApiKey:
      type: object
      properties:
        description:
          type: string
          description: The description of the API key.
        role:
          $ref: '#/components/schemas/ApiKeyRole'
          description: Role of the API Key
        rateLimitRpm:
          type: integer
          format: int32
          default: 100
          minimum: 1
          maximum: 1000
          description: The maximum number of API requests allowed per minute using this key. For Chat2Query Data Apps, you cannot modify this field.
        apiKeyExpireSetting:
          $ref: '#/components/schemas/ApiKeyApiKeyExpireSetting'
          description: The API Key expire setting
      description: 'An API key of a Data App. '
      required:
      - description
      - role
      - rateLimitRpm
x-tagGroups:
- name: Endpoints
  tags:
  - Data App
  - Data Source
  - Endpoint
  - Deployment
  - Data API Key
  - OpenAPI Specification