Onboarding Step 5: Create and sign your request

This onboarding section covers the steps on how to create and sign an Amazon Business API request. Before you proceed, make sure that you've created an app client on Developer Central and generated an access token and refresh token for your app client.

Step 1. Construct an Amazon Business API URI

Here's the components of an Amazon Business Partner API URI.

For example:

PUT https://na.business-api.amazon.com/example/2020-08-26/fooId?bar=bar_value

Step 2. Add headers to the URI

Add headers to the URI that you constructed in Step 1. Construct an Amazon Business API URI.
Here's the HTTP headers you've included in the requests.

Request headers

Here's an example of a request to the Amazon Business API with URI and headers but no signing information.

GET example/2020-08-26/fooId?bar=bar_value HTTP/1.1
 host: na.business-api.amazon.com
 user-agent: My Amazon Business Application Tool/2.0 (Language=Java/1.8.0.221;Platform=Windows/10)
 x-amz-access-token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSREXAMPLE
 x-amz-date: 20190430T123600Z

To sign a request to the Amazon Business API, proceed to Step 3. Create and sign your request.

Step 3. Create and sign your request

Amazon Business API uses the AWS Signature Version 4 Signing Process for authenticating requests. When you send HTTP requests to Amazon Business Partner API, you sign the requests so that Amazon Business can identify who sent them. You sign requests using your AWS access key, which consists of an access key ID and a secret access key.

📘

You need to learn how to sign HTTP requests only when you manually create them. When you use the AWS SDKs to calculate signatures for you, the SDK automatically signs the requests with the AWS access key that you specified during configuration.

Java developers, for example, can use AWS4Signer.java from the AWS SDK for Java as a model for calculating a signature. You can find SDKs for other languages in the AWS GitHub repository.

To create and sign your request, complete these:

• Create a canonical request

• Follow the instructions in Task 1: Create a Canonical Request for Signature Version 4 in the AWS documentation using this guidance:

  • Refer to Step 3. Add headers to the URI for an example of an unsigned request to start with when you create your canonical request.
  • Use SHA-256 for the hash algorithm.
  • Don't put authentication information in the query parameters. Put it in the Authorization header parameter. For information about using the Authorization header parameter for the authentication information, refer to Authorization header.

• Create a string to sign

• Follow the instructions in Task 2: Create a String to Sign for Signature Version 4 in the AWS documentation using this guidance:

  • The algorithm designation value is AWS4-HMAC-SHA256.
  • To determine the credential scope, refer to Credential scope.

• Calculate the signature

• Follow the instructions in Task 3: Calculate the Signature for AWS Signature Version 4 in the AWS documentation.

📘

Refer to Credential scope to help you complete this step.

• Add the signing information

• Follow the instructions in Task 4: Add the Signature to the HTTP Request in the AWS documentation using this guidance:

  • Don't add signing information to the query string. Add it to the Authorization header parameter.
  • Refer to Authorization header for details about creating an Authorization header parameter.

• The example shows what a request might look like after you've added the signing information using the Authorization header.

GET example/2020-08-26/fooId?bar=bar_value HTTP/1.1
 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIHV6HIXXXXXXX/20201022/us-east-1/execute-api/aws4\_request, SignedHeaders=host;user-agent;x-amz-access-token,
 Signature=5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924aEXAMPLE
 host: na.business-api.amazon.com
 user-agent: My Amazon Business Application Tool/2.0 (Language=Java/1.8.0.221;
 Platform=Windows/10)
 x-amz-access-token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSREXAMPLE
 x-amz-date: 20190430T123600Z

Credential scope

The credential scope is a component of the "string to sign" that you create when you sign a request to the Amazon Business API. Credential scope is represented by a slash-separated string of dimensions, as shown in the table.

For example:

20190430/us-east-1/execute-api/aws4_request

🚧

Important! Date in credential scope must match the date in your request.

The date stated in your credential scope must match the date in your request, as specified in the x-amz-date header. For more information, refer to Handling Dates in Signature Version 4 in the AWS documentation.

Authorization header

The Authorization header contains the signing information for a request. Although the header is named "Authorization", the signing information is used for authentication. Here's the components of an Authorization header.

For example:

For more information, refer to Step 3. Create and sign your request.

Response format

In response to an HTTP request, Amazon Business Partner API returns response headers and a JSON response message.

Response headers

Success Response

If your request is successful, Amazon Business API returns the data requested. Here's an example of a successful response.

HTTP/1.1 200 OK
Content-Length: 368
Content-Type: application/json
Date: Thu, 01 Jun 2020 22:23:31 GMT
x-amzn-RequestId: 6875f61f-6aa1-11e8-98c6-9bExample
{
  "payload": {
    "example_response_attribute": "2020-04-23"
  }
}

Error response

If your request is unsuccessful, Amazon Business API returns an error response. Here's the elements of the response message in an error response.

Response message

Here's an example of an error response.

HTTP/1.1 400 Bad Request
Content-Length: 117
Content-Type: application/json
Date: Fri, 01 Jun 2020 21:48:02 GMT
x-amzn-ErrorType: ValidationException
x-amzn-RequestId: a8c8d99a-6ab5-11e8-b0f8-19363980175b
{
  "errors": [
    {
      "message": "Access to requested resource is denied.",
      "code": "Unauthorized",
      "details": "Access token is missing in the request header."
    }
  ]
}

The Amazon Business API supports these HTTP methods.