API Keys in Data Service

The TiDB Cloud Data API supports both Basic Authentication and Digest Authentication.

• Basic Authentication uses non-encrypted base64 encoding to transmit your public key and private key. HTTPS ensures the transmission security. For more information, see RFC 7617 - The 'Basic' HTTP Authentication Scheme.
• Digest Authentication offers an additional security layer by hashing your public key, private key, a server-supplied nonce value, the HTTP method, and the requested URI before network transmission. This encrypts the private key to prevent it from being transmitted in plain text. For more information, see RFC 7616 - HTTP Digest Access Authentication.

API key overview

• An API key contains a public key and a private key, which act as the username and password required in the authentication. The private key is only displayed upon the key creation.
• Each API key belongs to one Data App only and is used to access the data in the TiDB Cloud clusters.
• You must provide the correct API key in every request. Otherwise, TiDB Cloud responds with a 401 error.

Rate limiting

Request quotas are subject to rate limits as follows:

• TiDB Cloud Data Service allows up to 100 requests per minute (rpm) per API key by default.

  You can edit the rate limit of an API key when you create or edit the key. The supported value range is from 1 to 1000. If your requests per minute exceed the rate limit, the API returns a 429 error. To get a quota of more than 1000 rpm per API key, you can submit a request to our support team.

  Each API request returns the following headers about the limit.

  • X-Ratelimit-Limit-Minute: The number of requests allowed per minute.
  • 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.
  • X-Ratelimit-Reset: The time in seconds at which the current rate limit resets.

  If you exceed the rate limit, an error response returns like this:

  HTTP/2 429
  date: Mon, 05 Sep 2023 02:50:52 GMT
  content-type: application/json
  content-length: 420
  x-debug-trace-id: 202309040250529dcdf2055e7b2ae5e9
  x-ratelimit-reset: 8
  x-ratelimit-remaining-minute: 0
  x-ratelimit-limit-minute: 10
  x-kong-response-latency: 1
  server: kong/2.8.1
  
  {"type":"","data":{"columns":[],"rows":[],"result":{"latency":"","row_affect":0,"code":49900007,"row_count":0,"end_ms":0,"limit":0,"message":"API key rate limit exceeded. The limit can be increased up to 1000 requests per minute per API key in TiDB Cloud console. For an increase in quota beyond 1000 rpm, please contact us: https://support.pingcap.com/hc/en-us/requests/new?ticket_form_id=7800003722519","start_ms":0}}}
  

• TiDB Cloud Data Service allows up to 100 requests per day for each Chat2Query Data App.

API key expiration

By default, API keys never expire. However, for security considerations, you can specify an expiration time for your API key when you create or edit the key.

• An API key is valid only before its expiration time. Once expired, all requests using that key will fail with a 401 error, and the response is similar as follows:

  HTTP/2 401
  date: Mon, 05 Sep 2023 02:50:52 GMT
  content-type: application/json
  content-length: 420
  x-debug-trace-id: 202309040250529dcdf2055e7b2ae5e9
  x-kong-response-latency: 1
  server: kong/2.8.1
  
  {"data":{"result":{"start_ms":0,"end_ms":0,"latency":"","row_affect":0,"limit":0,"code":49900002,"message":"API Key is no longer valid","row_count":0},"columns":[],"rows":[]},"type":""}
  

• You can also expire API keys manually. For detailed steps, see Expire an API key and Expire all API keys. Once you manually expire an API key, the expiration takes effect immediately.

• You can check the status and expiration time of your API keys in the Authentication area of your target Data App.

• Once expired, an API key cannot be activated or edited again.

Manage API keys

The following sections describe how to create, edit, delete, and expire API keys for a Data App.

Create an API key

To create an API key for a Data App, perform the following steps:

1. Navigate to the Data Service page of your project.

2. In the left pane, click the name of your target Data App to view its details.

3. In the Authentication area, click Create API Key.

4. In the Create API Key dialog box, do the following:

   1. (Optional) Enter a description for your API key.

   2. Select a role for your API key.

      The role is used to control whether the API key can read or write data to the clusters linked to the Data App. You can select the ReadOnly or ReadAndWrite role:

      • ReadOnly: only allows the API key to read data, such as SELECT, SHOW, USE, DESC, and EXPLAIN statements.
      • ReadAndWrite: 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.

   3. (Optional) Set a desired rate limit for your API key.

      If your requests per minute exceed the rate limit, the API returns a 429 error. To get a quota of more than 1000 requests per minute (rpm) per API key, you can submit a request to our support team.

   4. (Optional) Set a desired expiration time for your API key.

      By default, an API key never expires. If you prefer to specify an expiration time for the API key, click Expires in, select a time unit (Minutes, Days, or Months), and then fill in a desired number for the time unit.

5. Click Next. The public key and private key are displayed.

   Make sure that you have copied and saved the private key in a secure location. After leaving this page, you will not be able to get the full private key again.

6. Click Done.

Edit an API key

To edit the description or rate limit of an API key, perform the following steps:

1. Navigate to the Data Service page of your project.
2. In the left pane, click the name of your target Data App to view its details.
3. In the Authentication area, locate the Action column, and then click ... > Edit in the API key row that you want to change.
4. Update the description, role, rate limit, or expiration time of the API key.
5. Click Update.

Delete an API key

To delete an API key for a Data App, perform the following steps:

1. Navigate to the Data Service page of your project.
2. In the left pane, click the name of your target Data App to view its details.
3. In the API Key area, locate the Action column, and then click ... > Delete in the API key row that you want to delete.
4. In the displayed dialog box, confirm the deletion.

Expire an API key

To expire an API key for a Data App, perform the following steps:

1. Navigate to the Data Service page of your project.
2. In the left pane, click the name of your target Data App to view its details.
3. In the Authentication area, locate the Action column, and then click ... > Expire Now in the API key row that you want to expire.
4. In the displayed dialog box, confirm the expiration.

Expire all API keys

To expire all API keys for a Data App, perform the following steps:

1. Navigate to the Data Service page of your project.
2. In the left pane, click the name of your target Data App to view its details.
3. In the Authentication area, click Expire All.
4. In the displayed dialog box, confirm the expiration.