General Description
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 a 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 is a positive integer.
- The timestamp refers to the UTC time when the signature is created.
- The expirationPeriodInSeconds specifies the duration during which the signature remains valid.
- SignedHeaders includes the list of headers involved in the signature algorithm. The headers are separated by semicolons (e.g., host;x-bce-date) and arranged in lexicographical order. (This API signature involves only the host and x-bce-date headers.)
- The signature is a 256-bit signature represented as a 64-character lowercase hexadecimal digest.
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).
Communication protocol
Both HTTP and HTTPS methods are supported. For better data security, it is recommended to use HTTPS.
Request structure description
The data exchange format is JSON, and all request and response body content is encoded in UTF-8.
Request parameters include the following 4 types:
| Parameter type | Description |
|---|---|
| URI | Used to specify the operation entity, e.g., PUT /v1/user/{userName} |
| Query | Request parameters carried in the URL |
| HEADER | It is passed in through HTTP header, such as: x-bce-date |
| RequestBody | Request data body organized in JSON format |
Response structure description
Response values are in two forms:
| Response content | Description |
|---|---|
| HTTP STATUS CODE | Such as 200, 400, 403, 404, etc. |
| ResponseBody | Response data body organized in JSON format. |
Version No.
| Parameters | Types | Parameter location | Description | Required or not |
|---|---|---|---|---|
| version | String | URI parameter | API version number | Required |
Date and time
Dates and times can be expressed in various ways. For consistency, all date and time fields specified in the HTTP standard adhere to GMT unless otherwise stated. Other date and time formats consistently follow UTC time based on ISO 8601, with the following constraints:
- Date shall be expressed in the format of
YYYY-MM-DD, e.g.,2014-06-01represents June 1, 2014. - Time shall be expressed in the
hh:mm:ss+ capital letter Z format, and capital letter Z indicates UTC time, e.g.,23:00:10Zrepresents 23:00:10 UTC. - When involving date and time, insert an uppercase letter T between them, e.g.,
2014-06-01T23:00:10Zrepresents 23:00:10 UTC on June 1, 2014.
Normalized string
A string can usually contain any Unicode character. This flexibility can cause many troubles in programming. Therefore, the concept of “normalized string” is introduced. A normalized string contains only percent-encoded characters and URI (Uniform Resource Identifier) unreserved characters. RFC 3986 stipulates that URI unreserved characters include the following: letters (A-Z, a-z), numbers (0-9), hyphens (-), dots (.), underscores (_), and tildes (~). The way to convert any string into a normalized string is:
- Convert the string into a UTF-8 encoded byte stream.
- Leave all unreserved URI characters unchanged.
- Perform percent-encoding as described in RFC 3986 for the remaining bytes. Use a % symbol followed by two uppercase hexadecimal characters representing the byte value.
Example:
Original string: this is an example for testing,
Corresponding normalized string: this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95.