To send a Smart Access Gateway (SAG) API request, you must send an HTTP GET request to the SAG endpoint. You must add the request parameters that correspond to the API operation being called. After you call the API operation, the system returns a response. Requests and responses are encoded by using UTF-8.

Request syntax

SAG API operations use the RPC protocol. You can call SAG API operations by sending HTTP GET requests.

The request syntax is as follows:
http://endpoint/?Action=xx&parameters

Where:

  • Endpoint: the endpoint of the SAG API is smartag.cn-shanghai.aliyuncs.com.
  • Action: the name of the operation being performed. For example, to query SAG instances that you have created, you must set the Action parameter to DescribeSmartAccessGateways.
  • Version: the version of the API that you want to use. The current version of the SAG API is 2018-03-13.
  • Parameters: the request parameters for the operation. Separate multiple parameters with ampersands (&).

    Request parameters include both common parameters and operation-specific parameters. Common parameters include the API version number, authentication information, and other information.

The following example demonstrates how to call the DescribeSmartAccessGateways operation in SAG:

The following code has been formatted to improve readability.



https://smartag.cn-shanghai.aliyuncs.com/?Action=DescribeSmartAccessGateways
&Format=xml
&Version=2018-03-13
&Signature=xxxx%xxxx%3D
&SignatureMethod=HMAC-SHA1
&SignatureNonce=15215528852396
&SignatureVersion=1.0
&AccessKeyId=key-test
&Timestamp=2018-04-01T12:00:00Z

API authorization

To ensure the security of your account, we recommend that you call API operations in SAG as a RAM user. Before you call an API operation in SAG as a RAM user, you must create and attach required permission policies to the RAM user. For more information, see RAM authentication.

Request signatures

You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller.

SAG implements symmetric encryption with an AccessKey pair to verify the identity of the request sender. An AccessKey pair is an identity credential issued to Alibaba Cloud accounts and RAM users that is similar to a pair of logon username and password. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. The AccessKey ID is used to verify the identity of the user, while the AccessKey secret is used to encrypt and verify the signature string. You must keep your AccessKey secret strictly confidential.

You must add the signature to the RPC API request in the following format:

https://Endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
where:
  • SignatureMethod: the encryption method of the signature string. Set the value to HMAC-SHA1.
  • SignatureVersion: the version of the signature encryption algorithm. Set the value to 1.0.
  • SignatureNonce: a unique, random number used to prevent replay attacks. You must use different random numbers for different requests. We recommend that you use universally unique identifiers (UUIDs).
  • Signature: the signature string generated by symmetrically encrypting the request by using the AccessKey secret.

The following example demonstrates how a request to call the DescribeSmartAccessGateways API operation is signed. Assume that the AccessKey ID is testid and AccessKey secret is testsecret. The URL before being signed is as follows:



https://smartag.cn-shanghai.aliyuncs.com/?Action=DescribeSmartAccessGateways
&Timestamp=2016-04-23T12:46:24Z
&Format=XML
&AccessKeyId=testid
&SignatureMethod=HMAC-SHA1
&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
&Version=2018-03-13
&SignatureVersion=1.0

To calculate the signature, take the following steps:

  1. Use the request parameters to create a string-to-sign.
    GET&%2F&AccessKeyId%3Dtestid&Action%DescribeSmartAccessGateways&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion%3D1.0&Timestamp%3D2018-04-23T12%253A46%253A24Z&Version%3D2018-03-13
  2. Calculate the HMAC value of the string-to-sign. Append an ampersand (&) to the end of the AccessKey secret as the key to calculate the HMAC value. The key testsecret& is used in this example.
    The calculated signature string is as follows:
    CT9X0VtwR86fNWSnsc6v8YGOjuE=
  3. Add the signature string to the request:
    
    https://smartag.cn-shanghai.aliyuncs.com/?Action=DescribeSmartAccessGateways
    &Timestamp=2016-04-23T12:46:24Z
    &Format=XML
    &AccessKeyId=testid
    &SignatureMethod=HMAC-SHA1
    &SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
    &Version=2018-03-13
    &SignatureVersion=1.0
    &Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D