Tutorial: Create a private Selling Partner API application

This workflow creates a private Selling Partner API application.

🚧

Important!

If you decide you do not want to create a private SP-API app, you have the option to find a third-party app solution to replace your current business automation services. We encourage you to visit the Selling Partner Appstore, to review over 2,000 vetted apps that offer various automation solutions for your business needs. You can also search online for external companies that offer contracted developer services to help you create a private SP-API app.

Note: A private application is available only to your organization and is self-authorized. If you have a public application, go to Tutorial: Convert a public MWS application into a Selling Partner application.

The following diagram provides an overview of the workflow steps.

Workflow overview

Workflow steps:

  1. Select one selling account to create your developer profile.
  2. Request data access for your Selling Partner API application. (Developer Profile)
  3. Create and configure IAM resources.
    3.1 Create an AWS account.
    3.2 Create an IAM user.
    3.3 Create an IAM policy.
    3.4 Create an IAM role.
    3.5 Add an AWS Security Token Service (AWS STS) policy to your IAM user.
    3.6 (Optional) Verify that the STS policy is attached to your IAM user or role.
  4. Test the STS AssumeRole operation
  5. Create a private Selling Partner API application. (Developer Central)
  6. Implement self-authorization workflow. (Login with Amazon (LWA) token)
  7. Connect to the Selling Partner API. (Java SDK)
  8. Call your Selling Partner API endpoints.

Tutorial for creating private applications

This tutorial explains how to create a private Selling Partner API application.

Prerequisites

  • You must have an Amazon Web Services (AWS) account. To create an account, sign up for AWS.

Step 1. Select one selling account to create your developer profile.

In SP-API you only need to register one developer account, under a Seller or Vendor Central account, that will be able to access data across multiple regions to support all of your selling accounts. For the accounts your company has in other regions, you can authorize the created app using the Seller and Vendor Central authorization workflows.

Select the selling account where you would like to create your developer profile, and make sure you have access to it from Seller or Vendor central.

Step 2. Request the data access that your Selling Partner API application requires

  1. Sign in to Seller Central using your developer credentials.
  2. Navigate to Develop Apps.
  3. On the Developer Central page, choose View Profile.
  4. Data vended through SP-API must be treated securely, which requires developers to implement all the corresponding security mechanisms. On the Developer Profile page, answer the questions under Security Control section to provide information about how your organization meets these requirements. You can follow our Guidance to address key security controls in SP-API integration blog post to discover how to ensure that you meet the standards.
  5. On the Developer Profile page, in the Data Access section, choose the roles that your applications require. For more information on choosing or requesting roles, refer to Roles in the Selling Partner API.
  6. Choose Register.

The Developer Support team will evaluate your request and reply to your support case after their review is complete. This process may take several days. You can monitor your registration status in Developer Central on the Your developer registration is under review banner.

If your request is rejected, address the reported issues before submitting the form again.

Note: You cannot modify your Developer Profile while it is under review by Developer Support.

Step 3. Create and configure IAM policies and entities

AWS Identity and Access Management (IAM) resources are required for you to create a private Selling Partner API application, including an IAM user, IAM policy, and an IAM role.

You can programmatically create and configure the IAM resources by launching the Selling Partner API on AWS Quick Start.

The Selling Partner API on AWS Quick Start includes an AWS CloudFormation template that you deploy in your AWS account to programmatically create all of the required IAM policies and roles. Quick Start removes the chances of making mistakes in your configurations, as it is a fully automated process. You are responsible for the cost of the AWS services and any third-party licenses used while running this Quick Start reference deployment. If you choose to use the AWS Quick Start, launch the CloudFormation template, and then skip to Step 4. Test the STS AssumeRole operation.

Alternatively, Steps 3.1 through 3.6 explain how to manually create and configure IAM policies and entities with the end goal of creating an IAM role that you provide when you register your application. You will create an IAM user (with an AWS STS policy attached) that assumes an IAM role that has permissions to call the Selling Partner API.

Select to expand the manual steps to create and configure IAM policies.

When you create your IAM role, you also generate an Amazon Resource Name (ARN), which is a unique identifier for your IAM role. You must use this IAM role ARN when you create your private Selling Partner API application in Step 5. Create a private Selling Partner API application.

For more information about setting up AWS IAM, view the Integrate with Amazon SP-API: Set up AWS IAM video on the Amazon Seller University YouTube channel.

Step 3.1 Create an AWS account

You must have an AWS account because the Selling Partner API security model uses AWS authentication credentials. If you're not already an AWS customer, you can create a free AWS account. For more information, refer to AWS Free Tier.

Step 3.2 Create an IAM user

Create an IAM user to get AWS keys to authenticate calls to the Selling Partner API. We recommend creating a new IAM user exclusively for this purpose. Use the IAM user to assume the IAM role that you will create in Step 3.4 Create an IAM role.

  1. Sign in to the AWS Management Console, and then open the IAM console.

  2. From the left navigation pane, choose Users and then select Add users.

  3. On the Specify user details page, enter a user name.

Enter a username.

  1. Choose Next.

  2. On the Set permissions page, accept the defaults and then choose Next. You will set permissions when you create an IAM role.

  3. On the Review and create page, add any desired tags under the tags section.

Add a new tag.

  1. Choose Create user.

  2. In the User name column, select your new IAM user and navigate to the Security Credentials tab.

  3. Under the Access keys section, choose Create access key.

  4. On the Access key best practices & alternatives page choose Other, then choose Next.

  5. On the Set description tag (optional) page, add any desired description tag and then choose Create access key.

  6. On the Retrieve access keys page, choose Download .csv file to save the AWS access key and secret access key. Then, choose Done.

Retrieve access keys.

🚧

Important!

This is your only opportunity to view or download your AWS secret access key, which you must use to authenticate your calls to the Selling Partner API. Save the AWS access key ID and AWS secret access key in a safe and secure place. You will not have access to the AWS access key again after this step. If you lose your AWS secret access key you must create a new access key. You can have a maximum of two access keys (active or inactive) at a time. For more information about managing access keys, refer to Managing access keys (console).

  1. In the User name column, select your new IAM user again and record the User Amazon Resource Name (ARN). You will use the ARN in Step 3.4. Create an IAM role.

Record the user ARN.

For more information about creating IAM users, refer to Creating an IAM user in Your AWS account.

Step 3.3 Create an IAM policy

This IAM policy defines the permissions required to make calls to the Selling Partner API. Attach this policy to the IAM role that you will create in Step 3.4 Create an IAM role.

Note: If you use AWS Organizations to manage your AWS accounts, make sure your Organization level policy allows access to Selling Partner API. For more information, refer to Managing AWS Organizations policies.

  1. Sign in to the AWS Management Console, and then open the IAM console.

  2. From the left navigation pane, choose Policies.

    If this is your first time choosing Policies, choose Get Started.

  3. Choose Create policy.

  4. Choose the JSON tab.

  5. Paste this code into the text box (replacing the existing code), and then choose Next: Tags.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:*:*:*"
    }
  ]
}

Enter JSON.

  1. On the Add tags (Optional) page, add any desired tags, then choose Next: Review.

  2. On the Review policy page, name your policy SellingPartnerAPI and add an optional description. .

  3. Review the policy Summary, then choose Create policy.

Review and create policy.

For more information, refer to Creating IAM policies.

Step 3.4 Create an IAM role

Create an IAM role that trusts the IAM user that you created in Step 3.2 Create an IAM user and has permissions to call the Selling Partner API.

  1. Sign in to the AWS Management Console, and then open the IAM console.

  2. From the left navigation pane, select Roles and then choose Create role.

  3. On the Select trusted entity page, choose AWS account, and select one of the following depending on the account used to create your IAM user in Step 3.2 Create an IAM user:

  • If you created your IAM user in this same account, choose This account.
  • If you created your IAM user in a different account, choose Another AWS account. In the Account ID box, enter the account identifier for the AWS account where you created your IAM user in Step 3.2 Create an IAM user. The account identifier is the 12 digit number in the User ARN.

Select trusted entity.

  1. Choose Next.

  2. On the Add permissions page, in the filter box, type 'SellingPartnerAPI', select the policy, and then choose Next.

  3. On the Name, review, and create page, enter a role name in the Role name box, an optional role description in the Role description box, and then choose Create role.

Name, review, and create.

  1. Under Role name, select the name of your new role.

  2. On the Summary page, save your role ARN. You must have the role ARN for the following tasks:
    a. Add an AWS Security Token Service policy to your IAM user.
    b. Registering your Application.

Role summary page.

For more information, refer to Creating a role to delegate permissions to an IAM user.

Step 3.5 Add an AWS Security Token Service (AWS STS) policy to your IAM user

Adding an AWS Security Token Service (AWS STS) policy to your IAM user allows you to request temporary AWS access keys that you can use to authenticate your requests to the Selling Partner API. These credentials expire after a set period of time, which helps you control access to your AWS resources.

  1. Sign in to the AWS Management Console, and then open the IAM console.

  2. From the left navigation pane, select Users and then choose the user that requires the AWS STS policy. In this tutorial, choose the user you created in Step 3.2 Create an IAM user.

  3. On the Permissions tab, choose the Add permissions drop-down and choose Add inline policy.

  4. On the Create policy page, select Choose a service.

  5. Choose the STS service.

    Tip: Enter STS in the search box to filter your results.

  6. Under Actions, select the arrow next to Write.

  7. Choose AssumeRole.

Select Actions, write, and AssumeRole.

  1. Select the arrow next to Resources, and then choose Add ARN.

  2. In the Add ARN(s) dialog box, enter the role ARN from Step 3.4 Create an IAM role, choose Add, and then choose Review policy.

Add ARN.

  1. On the Review policy page, enter a name for your policy. Review your setting, then choose Create policy.

Step 3.6 (Optional) Verify that the STS policy is attached to your IAM user or role

  1. Sign in to the AWS Management Console, and then open the IAM console.

  2. Choose Users, then select your IAM user.

  3. Choose the Permissions tab, choose Add permissions, and then choose Add inline policy.

  4. On the Create policy page, select the JSON tab and paste the following code into the text box. This policy grants access for IAM to read any information related to IAM services.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:GenerateCredentialReport",
        "iam:GenerateServiceLastAccessedDetails",
        "iam:Get*",
        "iam:List*",
        "iam:SimulateCustomPolicy",
        "iam:SimulatePrincipalPolicy"
      ],
      "Resource": "*"
    }
  ]
}
  1. Choose Review policy, give a name for the policy (For example, PolicyNew), and choose Create policy.

Create policy

  1. Open AWS CloudShell and run the following commands to verify that the policy is attached to your IAM user or role:
  • Retrieve the inline policy document embedded in the specified IAM user:

    aws iam get-user-policy --user-name Bob --policy-name ExamplePolicy

  • List all managed policies attached to the specified IAM user:

    aws iam list-attached-user-policies --user-name Bob

  • Retrieve information about the specified managed policy:

    aws iam get-policy --policy-arn {{ARN of the policy}}

  • Retrieve policy details for the managed policy (use the version number obtained from previous step):

    aws iam get-policy-version --policy-arn {{ARN of the policy}} --version-id version number

Step 4. Test the STS AssumeRole operation

With the IAM resources created and the long-term user credentials generated, you can now test the STS AssumeRole operation, which will generate temporary credentials that you will use to sign SP-API requests. Follow the steps under Generate temporary credentials using AWS STS section of SP-API documentation to do it. As a result you should receive an AccessKeyId, SecretAccessKey and SessionToken.

Step 5. Create a private Selling Partner API application

In order to call the different endpoints, you will need to create a private SP-API application. This will give you access to client secrets that you have to use to sign your API requests.

  1. Sign in to Seller Central using your developer credentials.
  2. Navigate to Develop Apps.
  3. On the Developer Central page, next to your Amazon MWS application, choose Add new App Client.
  4. On the App registration form, for API Type, choose SP-API. This selection populates the form with your app details.
  5. In the IAM ARN box, paste the ARN for the IAM role that you created in Step 3. Create and configure IAM resources. If you are unsure of the ARN value, you can use the following processes:
    • If you created your IAM resources manually in Step 2, paste the ARN for the IAM role that you copied in Step 3.4 Create an IAM role. This IAM role should also have the AWS Security Token Service (AWS STS) policy attached.
    • If you created your IAM resources programmatically with the Selling Partner API on AWS Quick Start Deployment Guide, paste the ARN that you copied in Post-deployment steps - Copy the IAM role ARN.
    • To view the ARN in the AWS Management Console, sign in to the IAM Dashboard and in the left navigation pane, select Roles. Search for and select the SP-API role that you created. On the Summary page, copy the Role ARN.
  6. In the Roles section, select all roles required by your application. For more information on choosing or requesting roles, refer to Roles in the Selling Partner API.
  7. Choose Save and Exit to complete the registration and create a draft Selling Partner API application.

Step 6. Self-authorize your application

You can self-authorize your private application to access your account information. Before self-authorizing, you must register as a developer and register your application. You can self-authorize your application in draft status; there is no reason to publish a private application.

The self-authorization procedure varies depending whether you have a seller application or a vendor application. For these unique steps, refer to the following instructions:

Step 7. Connect to the Selling Partner API

After the set-up is completed, you are now good to execute a sample SP-API call. For this purpose, we recommend using Postman. Follow the steps under Using Postman for Selling Partner API models to import a model from the available API sections, generate an access token, retrieve temporary IAM credentials and make a call to an SP-API endpoint.

If you want to test the configuration from your code base, set up a workflow for calling operations in the Selling Partner API. This workflow includes exchanging Login with Amazon (LWA) tokens, constructing URIs, adding headers, and creating and signing requests. To set up this workflow, you can generate and use an SDK that includes LWA token exchange and authentication. For more information, refer to Generating a Java SDK with LWA token exchange and authentication and Connecting to the Selling Partner API using a generated Java SDK in the Selling Partner API Developer Guide.

For information about connecting to the Selling Partner API sandbox, refer to the Selling Partner API sandbox guide.

Step 8. Call your Selling Partner API endpoints

Update your application so that actions that previously called Amazon MWS operations will call the corresponding Selling Partner API operations. Refer to Mapping APIs from Amazon MWS to the Selling Partner API to determine which Selling Partner API operations correspond with which Amazon MWS operations.