Credentials

The process for obtaining credentials for the Amazon Advertising API is somewhat challenging. Ultimately the goal is to acquire a refresh token from Amazon, which the connector can use to access the customer’s data. The connector includes a command-line program, refresh_token.py, which must be used to obtain the refresh token from Amazon.

Customer Setup and Application

The steps that must be followed prior to getting a refresh token are documented here. At a high level, the customer must:

  1. Have an Amazon Advertising Console account.

  2. Issue an invitation to Zuar to create an Amazon Developer Account associated with the customer’s Advertising account.

  3. Create a Login with Amazon (LWA) account instructions here.

  4. After creating the LWA account, they will be redirected to a developer registration page.

    1. Important: do not click the Signin or Register buttons on the registration page.

    2. Provide the information requested on the page.

    3. Click the Get Started with Login with Amazon button

  5. They will be redirected to the Register new application page.

  6. Click the Register new application button.

  7. Provide the requested Application Information.

  8. Click Save

  9. Click the Web Settings sub-menu.

  10. Record the Client ID and Client Secret.

  11. In the Allowed URLs field, enter the value https://localhost:5000/signin. This value must be provided, despite it being labeled “optional”.

  12. Apply for API access process here. It can take 1-2 weeks for the customer to receive approval email from Amazon.

  13. Record the Whitelisted client id contained in the approval email.

  14. Provide the email address of their Zuar contact to Amazon and ask that Amazon add the email address to the customer’s Jira support account with Amazon.

The Client ID and Client Secret just obtained must be saved in a file. The contents of the file must look like the following:

ADV_API_CLIENT_ID="amzn1.application-oa2-client.6236b0f28ba9470c898cf8047ffaa1d8"
ADV_API_CLIENT_SECRET="d57e70b8f96d77e5a8e79e1edc5e6443707261ba137bc733df3a83d3d4b349b4"
ADV_API_SCOPE="cpc_advertising:campaign_management"

where the “id” and “secret” values are those from the above steps. These instructions will assume that the file is located at ~/aaapi_setup/env.

It is now possible to create a refresh token.

Zuar Developer Account Setup

  1. The individual for whom the customer issues a developer account invitation will receive an email from Amazon. Follow the instructions in the email; the process parallels that described above for the customer’s LWA account.

  2. View the settings for the Zuar account link here. It is unknown exactly which permissions are necessary. Either Administrator or Marketer are likely sufficient. Have the customer add permissions to the Zuar account, if necessary.

  3. Amazon documentation states that it is necessary to create a security profile in the developer account (here), but that seems to be unnecssary.

Once the Zuar account is setup, proceed to the next step: Create a Refresh Token.

Create a Refresh Token (i.e., Credentials)

The first step in getting a refresh token is to create an authorization URL that will be used by Zuar login to the Zuar Amazon developer account associated with the customer and b) grant access to Mitto, enabling it to access their data. When this is done, the URL in the address bar of their browser will contain an “access code”. The second step is to use the access code to obtain a refresh token.

The steps preformed with the cli must be performed by Zuar on the customer’s Mitto instance. The steps involving the browser can be performed by Zuar on any computer with a browser.

Create Authorization URL

On the Mitto instance:

  1. ssh in to the instance

  2. Get an authorization URL:

    cd ~
    mkdir aaapi_setup
    cd aaapi_setup
    source /opt/mitto/pyenv/bin/activate
    /opt/mitto-plugin-amazon-advertising/bin/refresh_token.py get_url
    
  3. An authorization URL will be output. It will look something like this:

    https://www.amazon.com/ap/oa?response_type=code&client_id=amzn1.application-oa2-client.6236b0f28ba9470c898cf8047ffaa1d8&redirect_uri=https://localhost:5000/signin&scope=cpc_advertising:campaign_management
    
  4. Copy the authorization URL.

Grant the Application Access

  1. Open a browser

  2. Paste the entire authorization URL into the address bar of the browser

  3. Press return

    1. A login page will appear. Zuar should login to their Amazon developer account associated with the customer.

    2. A page will appear asking if permission should be granted to the application. Click Allow.

  4. An error page will appear. It may either mention a possible ssl/security problem or an inaccessible page. Regardless of the error message, it can be ignored.

  5. Copy the entire contents of the browser’s address bar. It will look something like:

    https://localhost:5000/signin?code=ANyfFMmXpvoYjbXAvkzo&scope=cpc_advertising%3Acampaign_management&state=DPl3vCA3dxzmgZcPU2SYLTzNn9U1Su
    

    The code parameter in the URL is the “access code” used in the next step. In the example above, the code is ANyfFMmXpvoYjbXAvkzo.

    Important: the code expires in one hour. Once expired, a new code must be obtained by following the above steps.

Get a Refresh Token

The refresh token is the credential that will be used by Mitto to access customer data. It does not expire.

cd ~
mkdir aaapi_setup
cd aaapi_setup
source /opt/mitto/pyenv/bin/activate
/opt/mitto-plugin-amazon-advertising/bin/refresh_token.py get_url
  1. To get a refresh token, use the same Mitto ssh session above:

    /opt/mitto-plugin-amazon-advertising/bin/refresh_token.py --get_refresh_token CODE
    

    Replace CODE with the code obtained from the URL. For the above example, the command would be:

    /opt/mitto-plugin-amazon-advertising/bin/refresh_token.py --get_refresh_token ANyfFMmXpvoYjbXAvkzo
    

    The output of the command should look something like:

    {
     'access_token': ACCESSTOKENVALUE,
     'refresh_token': REFRESHTOKENVALUE,
     'token_type': 'bearer',
     'expires_in': 3600
    }
    

    An example with “real”, although truncated, tokens:

    {
     'access_token': 'Atza|IwEBIJXbkG...truncated...',
     'refresh_token': 'Atzr|IwEBICqcWU...truncated...',
     'token_type': 'bearer',
     'expires_in': 3600
    }
    
  2. Record the refresh_token value. This is the credential that will be used by the connector to access the customer’s data.

  3. The access_token is only valid for one hour. Test the access_token to ensure that it can be used to get customer data from the API.

    /opt/mitto-plugin-amazon-advertising/bin/refresh_token.py --get_data ACCESSTOKENVALUE
    

    JSON data from the customer’s Advertising account should appear as output.

    Using a “real” token from the above:

    /opt/mitto-plugin-amazon-advertising/bin/refresh_token.py --get_data 'Atza|IwEBIJXbkG...truncated...'
    

    Note that the token value must be quoted due to the pipe sybmol it contains.

Testing Credentials

Credentials (the refresh_token) can be tested using the wizard. If the wizard progresses past the first screen, the credentials are valid and were used to get the profile names displayed on the second page of the wizard.

However, if there is a desire to validate credentials via the cli, follow these steps. The refresh token itself can’t be used to get data from the API. However, it can be used to get a currently valid access token that can be used to get data. To test a refresh token:

On the customer’s Mitto instance.

  1. ssh in to the instance, then:

    cd ~
    mkdir aaapi_setup
    cd aaapi_setup
    source /opt/mitto/pyenv/bin/activate
    /opt/mitto-plugin-amazon-advertising/bin/refresh_token.py --get-access-token REFRESHTOKENVALUE
    

    The output of the command should look something like:

    {
     "access_token": "ACCESSTOKENVALUE",
     "refresh_token": "REFRESHTOKENVALUE",
     "token_type": "bearer",
     "expires_in": 3600
    }
    

    The ACCESSTOKENVALUE will be valid for one hour.

  2. Attempt to get customer data using the access token:

    /opt/mitto-plugin-amazon-advertising/bin/refresh_token.py --get_data ACCESSTOKENVALUE
    

    Customer data will be output if the refresh token was valid.

Resources

Version 3 of the API exists, but it is incomplete. We are using Version 2.

Basic onboarding/setup documentation.