General Description

API authentication mechanism

The Access Key and request signature mechanism are uniformly adopted for all API security authentication. Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings. For each HTTP request, use the algorithm described below to generate an authentication string. Submit the certification string in the Authorization header. The server verifies the correctness of the authentication string based on the generation algorithm. The certification string format is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}.

• The version should be a positive integer.
• The timestamp represents the UTC time when the signature is created.
• The expirationPeriodInSeconds parameter defines the signature's validity duration.
• signedHeaders is the list of headers involved in the signature algorithm. Separate headers with semicolons (;), such as host;x-bce-date. The list is sorted in lexicographical order. (This API signature only contains two headers of host and x-bce-date)
• The Signature is a 256-bit hash represented as a 64-character lowercase hex string.

When Baidu AI Cloud receives a user's request, the system will use the same SK and identical certification mechanism to generate a certification string, and then compare it with the certification string included in the user's request. If the authentication strings are the same, the system considers that the user possess the specified operation permission and proceeds with the relevant executions. If the authentication strings differ, the system will skip this operation and returns an error code. For detailed information on the authentication mechanism, please refer to [Authentication Mechanism](Reference/Authentication mechanism/Introduction.md).

Definition of password encryption transmission specification

All API parameters related to passwords must be encrypted; plaintext transmission is strictly prohibited. Passwords are encrypted using the AES 128-bit encryption algorithm, with the first 16 bits of the SK as the encryption key. The resulting binary byte stream from the encryption must then be converted to a hexadecimal format and transmitted to the server as a string. The process is as follows:

• byte[] bCiphertext = AES(plaintext, SK)
• String strHex = HexStr(bCiphertext)

Idempotence

When invoking the creation API, if a timeout or an internal server error occurs, the user can retry the request. In such cases, the clientToken parameter ensures no extra resources are created, thereby maintaining the request's idempotence.

Idempotence is based on clientToken, which is an ASCII string with a length not exceeding 64 bits, usually placed in the query string, such as

http://cce.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20

If a user calls the creation API with the same clientToken value, the server will return the same request result. Therefore, when a user retries after encountering an error, they can ensure that only one resource is created by providing the same clientToken value; if a user provides a previously used clientToken, but other request parameters (including queryString and requestBody) are different or even the URL Path is different, an error code of IdempotentParameterMismatch will be returned.

The clientToken remains valid for 24 hours, measured from the most recent reception by the server. This means if the client keeps sending the same clientToken, it will persist for an extended period.

Typesetting conventions

Request parameters

The data exchange format used is JSON, and all request/response body content is encoded in UTF-8.

Request parameters include the following 4 types:

Response value description

Response values are in two forms:

API version number