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.

NameDescriptionExample
HTTP methodOne of the Amazon Business API HTTP methods.GET
EndpointAn Amazon Business API Endpoint.https://na.business-api.amazon.com
PathThe Amazon Business API section/version. number of the section/resource./example/2020-08-26/foo
Query stringThe query parameters.?bar=bar_value
Path parameterThe path parameters.fooId

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

NameDescription
hostThe marketplace endpoint. Refer to Amazon Business API HTTP methods.
x-amz-access-tokenThe LWA access token. Refer to Onboarding Step 4: Authorizing Amazon Business API applications .
x-amz-dateThe date and time of your request.
user-agentYour application name and version number, platform, and programming language. These help Amazon diagnose and fix problems you might encounter with the service.

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:

📘

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.

DimensionDescriptionExample
DateAn eight-digit string representing the year (YYYY), month (MM), and day (DD) of the request.20190430
AWS regionThe region you are sending the request to. Refer to Amazon Business API Endpoint.us-east-1
ServiceThe service you are requesting. You can find this value in the endpoint. Refer to Amazon Business API Endpoint.execute-api
Termination stringA special termination string. For AWS Signature Version 4, the value is aws4_requestaws4_request.

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.

ComponentDescription
The algorithm used for signingThe hash algorithm used throughout the signing process. Amazon Business API requires SHA-256.
CredentialYour AWS access key ID plus the Credential scope. You get your AWS access key ID while creating IAM user.
SignedHeadersA list of all the HTTP headers that you included with the signed request.
SignatureThe signature calculated in Step 3. Create and sign your request.

For example:

Authorization: AWS4-HMAC-SHA256 Credential=AKIAIHV6HIXXXXXXX/20201022/us-east-1/execute-api/aws4_request, SignedHeaders=host;user-agent;x-amz-access-token;x-amz-date, Signature=5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924aEXAMPLE

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

NameDescription
Content-LengthStandard HTTP response header.
Content-TypeStandard HTTP response header.
DateStandard HTTP response header.
x-amzn-RequestIdRequest identifier. Include this if you contact us for support.

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

ElementDescriptionRequired
codeError code provided in API definitionYes
messageExplanation of the error condition.Yes
detailsLink to additional information.No

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.

HTTP methodDescription
GETRetrieves resource data or a list of resources.
POSTSubmits an entity to the specified resource, often causing a change in state or side effects on the server.
PUTReplaces all current representations of the target resource with the request payload.