Authentication

This guide will help developers in their first steps to use the Storefront API for Amazon. Notice that Storefront has to be setup properly as described in the Setup guide.

To securely connect to the Storefront API for Amazon, you must use the OAuth 2.0 protocol, the leading industry-standard protocol for authorization. The technical details are laid out in detail in RFC 6479. If you are simply a user of the Storefront API for Amazon, you can use one of the various OAuth 2.0 client libraries available for your platform of choice.

Prerequisites

To follow this tutorial, you will need:

1. A Storefront installation with a properly configured connection to Amazon Business as described in the Setup guide.
2. The domain name of your Storefront installation, e.g. example.com. We will use the placeholder YOUR_DOMAIN for the rest of this guide.
3. A pair of OAuth 2.0 credentials, called YOUR_CLIENT_ID and YOUR_CLIENT_SECRET for the rest of the document. They will be used to authenticate API requests. These credentials have been given to you during the initial setup of your connection.
4. The email address of a user that has an account on Amazon Business for the given organization, e.g. joe@example.com. We will use the YOUR_EMAIL_ADDRESS placeholder below.

caution

Remember to never share your YOUR_CLIENT_SECRET with anyone! Keep it safe, don't put it into source code, or share it with anyone. Treat it as if it were the PIN of your bank account.

Authenticating with the API

A central aspect of the OAuth 2.0 protocol is the so-called access token. The access token is used for authenticating requests to the Storefront API.

note

Notice that access tokens are short-lived with a lifetime of just a few minutes. That means you need to issue a new access token every now and then once the old one expires. According to the OAuth 2.0 specification, you create an access token by using YOUR_CLIENT_ID and YOUR_CLIENT_SECRET.

In Storefront API for Amazon, you create access tokens per user. That means that you must manage access tokens on the user level. You cannot use an access token issued for user A with user B.

We've designed Storefront API for Amazon as a machine-to-machine conversation. Hence we can use the so-called "Client Credentials" flow as outlined in the OAuth 2.0 protocol.

The following code creates an access token for the user with YOUR_EMAIL_ADDRESS.

cURL

curl --request POST \
     --url 'https://YOUR_DOMAIN/oauth/authorize' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data client_id=YOUR_CLIENT_ID \
     --data client_secret=YOUR_CLIENT_SECRET
     --data email=YOUR_EMAIL_ADDRESS

JavaScript

var axios = require("axios").default;

var options = {
  method: 'POST',
  url: 'https://YOUR_DOMAIN/oauth/authorize',
  headers: {'content-type': 'application/x-www-form-urlencoded'},
  data: {
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    email: 'YOUR_EMAIL_ADDRESS'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

C#

var client = new RestClient("https://YOUR_DOMAIN/oauth/token");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&email=YOUR_EMAIL_ADDRESS", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Java

HttpResponse<String> response = Unirest.post("https://YOUR_DOMAIN/oauth/authorize")
  .header("content-type", "application/x-www-form-urlencoded")
  .body("grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&email=YOUR_EMAIL_ADDRESS")
  .asString();

Go

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io"
)

func main() {
    // Configure your URL
    url := "https://YOUR_DOMAIN"

    // Ask for the client_credentials OAuth 2.0 flow
    data := url.Values{
        "grant_type":    []string{"client_credentials"},
        "client_id":     []string{YOUR_CLIENT_ID},
        "client_secret": []string{YOUR_CLIENT_SECRET},
        "email":         []string{YOUR_EMAIL_ADDRESS},
    }
    requestBody := strings.NewReader(data.Encode())

    // Prepare HTTP request
    req, err := http.NewRequest("POST", baseURL+"/oauth/authorize", requestBody)
    if err != nil {
        panic(err)
    }
    req.Header.Set("content-type", "application/x-www-form-urlencoded")

    // Execute the request
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // The HTTP response body will return JSON according to the OAuth 2.0 specification.
    body, err := io.ReadAll(req.Body)
    if err != nil {
        panic(err)
    }
    fmt.Println(resp)
    fmt.Println(string(body))
}

caution

Make sure to propertly encode the data in case you're having unusual symbols in e.g. the email address.

Parameters

Parameter	Description
grant_type	Set this to client_credentials to ask for the OAuth 2.0 Client Credentials flow.
client_id	Your OAuth Client ID.
client_secret	Your OAuth Client Secret.
email	The email address of the user you want to create the token for.

Response

If everything goes well, you will receive a successful HTTP response with status 200 OK with a payload containing the access_token, token_type, and expires_in values:

{
    "access_token": "HH3wr4...Neuz2PI",
    "token_type": "bearer",
    "expires_in": 300
}

Notice that the expires_in specifies the number of seconds until this access token expires.

note

If your access token is expired, you'll get a HTTP response with status 401 Unauthorized. Get yourself a new token when this happens.

Errors

In case of an error, you can use the HTTP status code and the response body to find out what went wrong.

HTTP Status Code	Description
400 Bad Request	The server understood your request but is unable to complete it, e.g. because a required parameter is missing.
401 Unauthorized	You sent invalid credentials.
500 Internal Server Error	Something went wrong on our side.

The HTTP response body if formatted according to the OAuth 2.0 Specification Section 5.2.

Example:

{
    "error": "invalid_request",
    "error_description": "Invalid request"
}