This document introduces the overall process for calling OpenAPI, interface call limitations, and common error codes, with a focus on the essential token application and usage methods required when calling OpenAPI.

1. A client ID and client secret are generated for each OpenAPI client; these serve as credentials for calling the interface.
2. The user uses the client ID and client secret to call the interface and obtain a JWT token containing user identity information.
3. When calling business interfaces, the user needs to include the JWT token in the request header, for example: Authorization: Bearer jwt_token.
4. When the interface is called, DataAgent uses the public key to verify the JWT token and gateway token, and performs rate limiting checks and auditing.
5. When calling any DataAgent interface, to facilitate troubleshooting, it is recommended to add x-request-id and request-id (ensure the string is unique) to the request headers. Two headers are needed because DataAgent consists of multiple components, and different components may use different identifiers. These two parameters will be recorded in DataAgent's backend logs, helping you analyze and locate issues more efficiently, thereby enabling faster resolution of potential faults.
6. Return business results.

The overall process is as follows:

Obtain clientId and clientSecret #

1. Create credentials.
   Go to the "Open Platform" - "Credential Management" page, click "Create Credential" to apply for ClientId and ClientSecret. The credential types are divided into two categories: user and system (only supported for system administrators).

2. You can copy the ClientId and ClientSecret you received.

Obtain jwtToken #

Request URL: The interface URL varies depending on the environment.

• If it is a self-hosted deployment environment, the prefix of the interface URL matches the access address of the self-hosted environment.

Request example #

# Replace the clientId and clientSecret
curl --location --request POST 'https://console.volcengine.com/aeolus/api/v3/openapi/jwtToken' \
-H 'Content-Type: application/json' \

-d '{
  "metadata": {
    "clientId": "{clientId}",
    "clientSecret": "{clientSecret}",
    "proxyUser": "abc****@21**********",
    "expire": 3600
  }
}'

Request parameters #

Response parameters #

Response example #

{
    "code": "aeolus/ok",
    "data": {
        "jwtToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ey*****************************************************************************************************************************************************************************.********************-*************************************************************************************-****************************************************************************************************************************-***-********************************************-******************************************************-*************************-****************************************************************************-************-*************************************-*********************************************************************************************************************************************************-****************-******************5sus",
        "proxyUser": "user_1"
    },
    "msg": "成功" //which means "success"
}

When calling the interface, the user needs to include the content of jwtToken in the request header, for example: Authorization: Bearer jwt_token
The following is an example of calling the interface for the current user using curl:

curl -X GET 'https://{domain}/aeolus/api/v3/open/misc/current_user' \
-H 'Authorization: Bearer jwt_token'

To ensure service stability and prevent malicious attacks, the DataAgent backend uses the following methods to limit requests:
(1) Rate limiting (the current interface's external service capacity has reached a high level; if it still does not meet your requirements, you can contact the Volcano Engine technical support team to request modifications);
(2) Blocking, used to reserve some APIs as not open or to temporarily block abnormal user requests;
(3) Auditing, every openapi call will be recorded, including the caller, interface, parameters, and call time.

For details, see Reference: Common Error Codes.