• Cloud Search Service

  1. Help Center
  2. Cloud Search Service
  3. API Reference
  4. Environment Preparation
  5. Obtaining Request Authentication Information

Obtaining Request Authentication Information

You can use either of the following authentication methods to call APIs:

  • Token authentication: Requests are authenticated using tokens.
  • AK/SK authentication: Requests are encrypted using the access key (AK) and secret key (SK). AK/SK authentication is recommended because it provides higher security than token authentication.

Token Authentication

To use token authentication, obtain the user token, and add X-Auth-Token to the request header of the service API when making an API call.

  1. Send POST https://IAM endpoint/v3/auth/tokens

    To obtain the Identity and Access Management (IAM) endpoint and the region name in the message body. For details, see Regions and Endpoints.

    An example request message is as follows:

    Replace the variables in italics in the following example with actual ones. For details, see Obtaining the User Token in Identity and Access Management API Reference. The parameter description is as follows:

    • username: indicates the username used for login.
    • password: indicates the password used for login.
    • domainname: indicates the name of an enterprise account to which a user belongs. If there is no enterprise account, enter the username.
    • project name: indicates the project name, for example, eu-de.
      "auth": {
        "identity": {
          "methods": [
          "password": {
            "user": {
              "name": "username",
              "password": "password",
              "domain": {
                "name": "domainname"
        "scope": {
          "project": {
             "name": "eu-de"//Assume that the region name is eu-de.

  2. Obtain the token. For details, see section Obtaining the User Token in the Identity and Access Management API Reference. The token value is the X-Subject-Token value in the response header.
  3. Make a call to a service API, add X-Auth-Token to the message header, and set the value of X-Auth-Token to the token obtained in 2.

AK/SK Authentication

Use the AK/SK encryption method to verify the identity of a request sender. If you use the AK/SK for authentication, you must obtain the signature through the request signing process and add the signature to the headers of API requests.


AK: indicates the ID of the access key. It is the unique identifier associated with the SK. The AK and SK are used together to obtain an encrypted signature for a request.

SK: indicates the secret access key together used with the access key ID to sign requests. AK and SK can be used together to identify a request sender to prevent the request from being modified.

  • Demo code

    Download the demo from the following URL: https://github.com/api-gate-way/SdkDemo

  • API gateway signature tool

    If you do not use the demo project, you can download the API gateway signature tool and reference it in other projects.

    Decompress the downloaded package and reference the extracted JAR file to the dependent path. See the following figure.
    Figure 1 Referencing the JAR file

The following uses the demo code to show how to sign a request and how to use an HTTP client to send an HTTPS request:

  1. Obtain an AK/SK file. If an AK/SK file has been obtained, skip this step and find the AK/SK file that has been downloaded. Generally, the file name is credentials.csv.

    1. Sign up and log in to the management console.
    2. Click the username and choose My Credential from the drop-down list.
    1. On the My Credential page, click Access Keys.
    2. Click Add Access Key to switch to the Add Access Key page.
    3. Enter the password used for the current login.
    4. Enter the verification code sent to your mailbox or mobile phone.

      For users created in IAM, if no email address or mobile phone is specified during user creation, you only need to authenticate the login password.

    5. Click OK to download the access key.

      To prevent the access key from being leaked, keep it secure.

  2. Download the demo and decompress it.

    Download the demo from the following URL: https://github.com/api-gate-way/SdkDemo

  3. Import the sample project to Eclipse.

    Figure 2 Selecting an existing project
    Figure 3 Selecting the decompressed sample code
    Figure 4 Project structure example

  4. Sign the request.

    The signature method is integrated into the referenced JAR file. Before sending the request, you need to sign the requested content. The signature obtained is included in the HTTP header of the request.

    The demo code has three classes for demonstration:

    • AccessService: indicates the abstract class that converts the GET, POST, PUT, and DELETE methods in to the access method.
    • Demo: indicates the execution entry used to simulate GET, POST, PUT, and DELETE request sending.
    • AccessServiceImpl: indicates the implementation of the access method. Code required for API gateway communication is in the access method.
    1. Add a request header.

      In the AccessServiceImpl.java file, locate the following rows:

      //TODO: Add special headers. 
      //request.addHeader("X-Project-Id", "xxxxx"); 
      //request.addHeader("X-Domian-Id", "xxxxx");

      Modify the preceding code as follows:

      //TODO: Add special headers. 
      request.addHeader("Content-Type", "application/json");
      • Content-Type: Set this parameter based on the MIME type of the actual sent request body. Currently, application/json and text/xml are supported.
    2. Edit the main method in the Demo.java file to replace the following content with actual values.

      Replace the texts in bold in the following sample with actual values. To call other methods such as POST, PUT, and DELETE, see the corresponding comment method.

      You have to specify region, serviceName, ak, sk, and url based on your requirements. In the demo, the URL for obtaining the VPC is used. For details about how to obtain project_id in the URL, see Obtaining a Project ID. For details about the endpoint, see Regions and Endpoints.

      //TODO: Replace region with the name of the region in which the service to be accessed is located.  
      private static final String region = ""; 
      //TODO: Replace vpc with the name of the service you want to access. For example, ecs, vpc, iam, and elb. 
      private static final String serviceName = ""; 
      public static void main(String[] args) throws UnsupportedEncodingException 
      //TODO: Replace the AK and SK with those obtained on the My Credential page. 
      String ak = "ZIRRKMTWP******1WKNKB"; 
      String sk = "Us0mdMNHk******YrRCnW0ecfzl"; 
      //TODO: To specify a project ID (multi-project scenarios), add the X-Project-Id header. 
      //TODO: To access a global service, such as IAM, DNS, CDN, and TMS, add the X-Domain-Id header to specify an account ID. 
      //TODO: To add a header, find "Add special headers" in the AccessServiceImple.java file. 
      //TODO: Test the API 
      String url = "https://{Endpoint}/v1/{project_id}/vpcs"; 
      get(ak, sk, url); 
      //TODO: When creating a VPC, replace {project_id} in postUrl with the actual value. 
      //String postUrl = "https://serviceEndpoint/v1/{project_id}/cloudservers"; 
      //String postbody ="{\"vpc\": {\"name\": \"vpc\",\"cidr\": \"\"}}"; 
      //post(ak, sk, postUrl, postbody); 
      //TODO: When querying a VPC, replace {project_id} in url with the actual value. 
      //String url = "https://serviceEndpoint/v1/{project_id}/vpcs/{vpc_id}"; 
      //get(ak, sk, url); 
      //TODO: When updating a VPC, replace {project_id} and {vpc_id} in putUrl with the actual values. 
      //String putUrl = "https://serviceEndpoint/v1/{project_id}/vpcs/{vpc_id}"; 
      //String putbody ="{\"vpc\":{\"name\": \"vpc1\",\"cidr\": \"\"}}"; 
      //put(ak, sk, putUrl, putbody); 
      //TODO: When deleting a VPC, replace {project_id} and {vpc_id} in deleteUrl with the actual values. 
      //String deleteUrl = "https://serviceEndpoint/v1/{project_id}/vpcs/{vpc_id}"; 
      //delete(ak, sk, deleteUrl); 
    3. Compile and run the code to make an API call.

      Choose Package Explorer > Demo.java. Right-click Run AS and choose Java Application.

      You can view the API calling logs on the console.