openapi: 3.2.0
info:
title: TiDB Cloud Data Service OPEN Data API Key API
description: "# Overview\n\nThe TiDB Cloud Data Service API provides a [RESTful interface](https://en.wikipedia.org/wiki/Representational_state_transfer) for programmatically managing administrative objects within the [TiDB Cloud Data Service](https://docs.pingcap.com/tidbcloud/data-service-overview). Through this API, you can manage the following resources automatically and efficiently:\n\n* **Data App**: a collection of endpoints that you can use to access data for a specific application.\n* **Data Source**: clusters linked to Data Apps for data manipulation and retrieval.\n* **Endpoint**: a web API that you can customize to execute SQL statements. You can specify parameters for the SQL statements, such as the value used in the `WHERE` clause. When a client calls an endpoint and provides values for the parameters in a request URL, the endpoint executes the SQL statement with the provided parameters and returns the results as part of the HTTP response.\n* **Deployment**: the process of deploying Data Apps.\n* **Data API Key**: used for secure endpoint access. This key is used to access data in the TiDB Cloud clusters, whereas the TiDB Cloud organization API key is used to manage resources such as projects, clusters, Data Apps, and endpoints.\n* **OpenAPI Specification**: Data Service supports generating the OpenAPI Specification 3.0 for each Data App, which enables you to interact with your endpoints in a standardized format. You can use this specification to generate standardized OpenAPI documentation, client SDKs, and server stubs.\n\n# Get Started\n\nThis guide helps you make your first API call to TiDB Cloud Data Service API. You'll learn how to authenticate a request, build a request, and interpret the response. The [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps) endpoint is used in this guide as an example.\n\n## Prerequisites\n\nTo complete this guide, you need to perform the following tasks:\n\n- Create a [TiDB Cloud account](https://tidbcloud.com/free-trial)\n- Install [curl](https://curl.se/)\n\n## Step 1. Create an organization API key\n\nTo create an organization API key, log in to your TiDB Cloud console. Navigate to the [**API Keys**](https://tidbcloud.com/org-settings/api-keys) page of your organization, and create an API key.\n\nAn organization API key contains a public key and a private key. Copy and save them in a secure location. You will need to use the API key later in this guide.\n\nFor more details about creating an organization API key, refer to [API Key Management](#section/Authentication/API-Key-Management).\n\n## Step 2. Make your first API call\n\n### Build an API call\n\nTiDB Cloud Data Service API call consists of the following components:\n\n- **A host.** The host for TiDB Cloud Data Service API is <https://dataservice.tidbapi.com>.\n- **An organization API Key**. The public key and the private key are required for authentication.\n- **A request.** When submitting data to a resource via `POST`, `PATCH`, or `PUT`, you must submit your payload in JSON.\n\nIn this guide, you call the [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps) endpoint. For a detailed description of the endpoint, see the [API reference](#tag/Data-App/operation/DataApp_ListDataApps).\n\n### Call an API endpoint\n\nTo get all Data Apps in your project, run the following command in your terminal. Replace `YOUR_PUBLIC_KEY`, `YOUR_PRIVATE_KEY`, and `YOUR_PROJECT_ID` with your actual values. To get the project ID, you can call the [List all accessible projects](https://docs.pingcap.com/tidbcloud/api/v1beta#tag/Project/operation/ListProjects) endpoint.\n\n```bash\ncurl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps?projectId=YOUR_PROJECT_ID'\n```\n\n## Step 3. Check the response\n\nAfter making the API call, if the status code in response is `200` and you see details about all the Data Apps in your project, your request is successful. Here is an example of a successful response.\n\n```log\n{\n \"dataApps\": [\n {\n \"dataAppId\": \"{data_app_id}\",\n \"name\": \"dataApps/{data_app_id}\",\n \"version\": \"\",\n \"projectId\": \"{project_id}\",\n \"clusterIds\": [],\n \"appType\": \"DATAAPP\",\n \"displayName\": \"New Data App\",\n \"description\": \"\",\n \"createdAt\": \"2023-06-03T06:52:08Z\",\n \"updatedAt\": \"2023-06-03T06:52:08Z\"\n },\n {\n \"dataAppId\": \"{data_app_id}\",\n \"name\": \"dataApps/{data_app_id}\",\n \"version\": \"\",\n \"projectId\": \"{project_id}\",\n \"clusterIds\": [],\n \"appType\": \"CHAT2QUERY\",\n \"displayName\": \"New App\",\n \"description\": \"\",\n \"createdAt\": \"2023-06-03T06:52:08Z\",\n \"updatedAt\": \"2023-06-03T06:52:08Z\"\n }\n ],\n \"nextPageToken\": \"\"\n}\n```\n\nIf your API call is not successful, you will receive a status code other than `200` and the response looks similar to the following example. To troubleshoot the failed call, you can check the `message` in the response.\n\n```log\n{\n \"code\": 403,\n \"message\": \"Request error, projectId not exist\",\n \"details\": []\n}\n```\n\n# Call a Deployed Data Service Endpoint\n\nIf you have deployed a Data Service endpoint, you can call it using the Data API key. To begin, follow these steps:\n\n1. Generate a Data API key by calling the [Create an API key for a Data App](#tag/Data-API-Key/operation/APIKey_CreateApiKey) endpoint. You can run the following `curl` command and replace `YOUR_PUBLIC_KEY`, `YOUR_PRIVATE_KEY`, and `YOUR_DATAAPP_ID` with your actual values. Note that `YOUR_PUBLIC_KEY` and `YOUR_PRIVATE_KEY` are [organization API keys](#section/Authentication/Organization-API-key-overview).\n\n ```bash\n curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request POST \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/YOUR_DATAAPP_ID/apiKeys'\\\n --header 'Content-Type: application/json' \\\n --data '{\n \"description\": \"A new API Key\",\n \"role\": \"READ_AND_WRITE\",\n \"rateLimitRpm\": 100\n }'\n ```\n\n2. Call the deployed endpoint. Suppose that you have created a `GET` endpoint named `/hello`, with the request URL as `https://data.tidbcloud.com/api/v1beta/app/DATAAPP_ID/endpoint/hello`. To call this endpoint, replace `YOUR_DATAAPP_PUBLIC_KEY` and `YOUR_DATAAPP_PRIVATE_KEY` with the values obtained from the response in step 1, and replace `YOUR_DATAAPP_ID` with the actual Data App ID in the following command:\n\n ```bash\n curl --location-trusted --digest \\\n --user 'YOUR_DATAAPP_PUBLIC_KEY:YOUR_DATAAPP_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://data.tidbcloud.com/api/v1beta/app/YOUR_DATAAPP_ID/endpoint/hello'\n ```\n \n For improved performance, you can call the endpoint using the regional domain name. Replace `REGION` with the specific region name to which the cluster belongs, such as `us-west-2`.\n \n ```bash\n curl --digest \\\n --user 'YOUR_DATAAPP_PUBLIC_KEY:YOUR_DATAAPP_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://REGION.data.tidbcloud.com/api/v1beta/app/DATAAPP_ID/endpoint/hello'\n ```\n\n# Authentication\n\nThe TiDB Cloud Data Service API uses [HTTP Digest Authentication](https://en.wikipedia.org/wiki/Digest_access_authentication). It protects your private key from being sent over the network. For more details about HTTP Digest Authentication, refer to the [IETF RFC](https://datatracker.ietf.org/doc/html/rfc7616).\n\n## Organization API key overview\n\n- The organization API key contains a public key and a private key, which act as the username and password required in the HTTP Digest Authentication. The private key only displays upon the key creation.\n- The organization API key belongs to your organization and acts as the `Organization Owner` role. You can check [permissions of owner](https://docs.pingcap.com/tidbcloud/manage-user-access#configure-member-roles).\n- You must provide the correct organization API key in every request. Otherwise, TiDB Cloud responds with a `401` error.\n\n## Organization API key management\n\n### Create an organization API key\n\nOnly the **owner** of an organization can create an organization API key.\n\nTo create an organization API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **Create API Key**.\n4. Enter a description for your API key. The role of the API key is always `Organization Owner` currently.\n5. Click **Next**. Copy and save the public key and the private key.\n6. Make sure that you have copied and saved the private key in a secure location. The private key only displays upon the creation. After leaving this page, you will not be able to get the full private key again.\n7. Click **Done**.\n\n### View details of an organization API key\n\nTo view details of an organization API key, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. You can view the details of the API keys on the page.\n\n### Edit an organization API key\n\nOnly the **owner** of an organization can modify an organization API key.\n\nTo edit an organization API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to change, and then click **Edit**.\n4. You can update the API key description.\n5. Click **Update**.\n\n### Delete an organization API key\n\nOnly the **owner** of an organization can delete an organization API key.\n\nTo delete an organization API key in an organization, perform the following steps:\n\n1. In the [TiDB Cloud console](https://tidbcloud.com), switch to your target organization using the combo box in the upper-left corner.\n2. In the left navigation pane, click **Organization Settings** > **API Keys**.\n3. On the **API Keys** page, click **...** in the API key row that you want to delete, and then click **Delete**.\n4. Click **I understand, delete it.**\n\n# Rate Limiting\n\nThe TiDB Cloud Data Service API allows up to 100 requests per minute per API key. If you exceed the rate limit, the API returns a `429` error. For more quota, you can [submit a request](https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519) to contact our support team.\n\nEach API request returns the following headers about the limit.\n\n- `X-Ratelimit-Limit-Minute`: The number of requests allowed per minute. It is 100 currently.\n- `X-Ratelimit-Remaining-Minute`: The number of remaining requests in the current minute. When it reaches `0`, the API returns a `429` error and indicates that you exceed the rate limit.\n- `X-Ratelimit-Reset`: The time in seconds at which the current rate limit resets.\n\nIf you exceed the rate limit, an error response returns like this.\n\n```\n> HTTP/2 429\n> date: Fri, 22 Jul 2022 05:28:37 GMT\n> content-type: application/json\n> content-length: 66\n> x-ratelimit-reset: 23\n> x-ratelimit-remaining-minute: 0\n> x-ratelimit-limit-minute: 100\n> x-kong-response-latency: 2\n> server: kong/2.8.1\n\n> {\"details\":[],\"code\":49900007,\"message\":\"The request exceeded the limit of 100 times per apikey per minute. For more quota, please contact us: https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519\"}\n```\n\n# API Changelog\n\nThis changelog lists all changes to the TiDB Cloud Data Service API.\n\n<!-- In reverse chronological order -->\n\n## 20250812\n\n- \"TiDB Cloud Serverless\" is renamed to \"TiDB Cloud Starter\".\n\n## 20240910\n\n- The [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings) endpoint removes the support for the `gpt-3.5-turbo` model and adds support for `gpt-4o` and `gpt-4o-mini` models.\n\n- \"TiDB Serverless\" is renamed to \"TiDB Cloud Serverless\".\n- \"TiDB Dedicated\" is renamed to \"TiDB Cloud Dedicated\".\n\n## 20240806\n\n- Add the [List all system endpoints in a Data App](#tag/Data-App/operation/DataAppsService_GetSystemEndpointConfig) endpoint.\n\n- Add the [Update the configuration of system endpoints](#tag/Data-App/operation/DataAppsService_UpdateSystemEndpointConfig) endpoint.\n\n## 20240716\n\n- The [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings) endpoint removes the support for Claude models.\n\n## 20240528\n\n- Initial release of the TiDB Cloud Data Service API, including the following resources and endpoints:\n\n - Data App:\n - [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps)\n - [Create a Data App](#tag/Data-App/operation/DataApp_CreateDataApp)\n - [Get Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_GetChat2QuerySettings)\n - [Update Chat2Query Data App settings by ID](#tag/Data-App/operation/DataApp_UpdateChat2QuerySettings)\n - [Update a Data App](#tag/Data-App/operation/DataApp_UpdateDataApp)\n - [Get a Data App by ID](#tag/Data-App/operation/DataApp_GetDataApp)\n - [Delete a Data App](#tag/Data-App/operation/DataApp_DeleteDataApp)\n - Data Source:\n - [List all data sources in a Data App](#tag/Data-Source/operation/DataSource_ListDataSources)\n - [Create a data source for a Data App](#tag/Data-Source/operation/DataSource_CreateDataSource)\n - [Get a data source by ID](#tag/Data-Source/operation/DataSource_GetDataSource)\n - [Delete a data source for a Data App](#tag/Data-Source/operation/DataSource_DeleteDataSource)\n - Endpoint:\n - [List all endpoints in a Data App](#tag/Deployment/operation/Deployment_ListDeployments)\n - [Create an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_CreateEndpoint)\n - [Update an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_UpdateEndpoint)\n - [Get an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_GetEndpoint)\n - [Delete an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_DeleteEndpoint)\n - [Test an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_TestEndpoint)\n - Deployment:\n - [List all deployments for a Data App](#tag/Deployment/operation/Deployment_ListDeployments)\n - [Create a deployment for a Data App](#tag/Deployment/operation/Deployment_CreateDeployment)\n - [Get a deployment by ID](#tag/Deployment/operation/Deployment_GetDeployment)\n - Data API Key:\n - [List all API keys for a Data App](#tag/Data-API-Key/operation/APIKey_ListApiKeys)\n - [Create an API key for a Data App](#tag/Data-API-Key/operation/APIKey_CreateApiKey)\n - [Update an API key for a Data App](#tag/Data-API-Key/operation/APIKey_UpdateApiKey)\n - [Get an API key by ID](#tag/Data-API-Key/operation/APIKey_GetApiKey)\n - [Delete an API key for a Data App](#tag/Data-API-Key/operation/APIKey_DeleteApiKey)\n - OpenAPI Specification:\n - [Get the OpenAPI Specification of a Data App](#tag/OpenAPI-Specification/operation/APISpecification_GetApiSpec)\n"
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](https://docs.pingcap.com/tidbcloud/api/v1beta#section/Authentication). 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:
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`"
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.
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
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
protobufAny:
type: object
properties:
'@type':
type: string
additionalProperties: {}
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
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."
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"
x-tagGroups:
- name: Endpoints
tags:
- Data App
- Data Source
- Endpoint
- Deployment
- Data API Key
- OpenAPI Specification