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 overviewWorkflow overview

Workflow steps:

  1. Request data access for your Selling Partner API application. (Developer Profile)
  2. Create and configure IAM resources.
    2.1 Create an AWS account.
    2.2 Create an IAM user.
    2.3 Create an IAM policy.
    2.4 Create an IAM role.
    2.5 Add an AWS Security Token Service (AWS STS) policy to your IAM user.
    2.6 (Optional) Verify that the STS policy is attached to your IAM user or role.
  3. Create a private Selling Partner API application. (Developer Central)
  4. Implement self-authorization workflow. (Login with Amazon (LWA) token)
  5. Connect to the Selling Partner API. (Java SDK)
  6. 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. 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. 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.
  5. 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.

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

Step 2. Create and configure IAM resources

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.

Steps 2.1 through 2.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.

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 3.

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.

Note: Alternatively, 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. 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 3. Create a private Selling Partner API application.

Step 2.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 2.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 create in Step 2.4 Create an IAM role.

Use the following procedure to create an IAM user

  1. Sign in to the AWS Management Console, and then open the IAM console at console.aws.amazon.com/iam.

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

  3. Enter a user name.

  4. Select Access Key - Programmatic access and then choose Next: Permissions.

Enter use name and select access typeEnter use name and select access type

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

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

  3. On the Add tags (optional) page, add any desired tags, and then choose Next: Review.

  4. On the Review page, ignore the This user has no permissions warning. You will set permissions when you create an IAM role.

Review pageReview page

  1. Choose Show to view the AWS secret access key. To save the AWS access key, select Download .csv, and then save the file to a safe location.

Secret access keySecret access key

🚧

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 IAM user with a new set of keys.

  1. Choose Close.

  2. In the User name column, select your new IAM user to view and record the User ARN. You will use the ARN in Step 2.4 Create an IAM role.

Record user ARNRecord user ARN

For more information about creating IAM users, refer to Creating an IAM User in Your AWS Account in the AWS documentation.

Step 2.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 create in Step 2.4 Create an IAM role.

Note: If your AWS account leverages AWS Organizations you must ensure that your organization level policy allows access to the Selling Partner API. For more information, refer to Managing AWS Organizations policies in the AWS documentation.

Use the following procedure to create an IAM policy

  1. Sign in to the AWS Management Console, and then open the IAM console at console.aws.amazon.com/iam.

  2. From the left navigation pane, select Policies.

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

  3. Select Create policy.

  4. Choose the JSON tab.

  5. Paste the following 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 JSONEnter JSON

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

  2. On the Review policy page, enter a Name and a Description (optional) for the policy that you are creating. We recommend naming your IAM policy, SellingPartnerAPI.

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

Review and create policyReview and create policy

For more information, refer to Creating IAM Policies in the AWS documentation.

Step 2.4 Create an IAM role

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

Use the following procedure to create an IAM role

  1. Sign in to the AWS Management Console, and then open the IAM console at console.aws.amazon.com/iam.

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

  3. On the Select trusted entity page, under Trusted entity type, choose AWS account.

  4. On the Select trusted entity page, under An AWS account, choose Another AWS account.

  5. In the Account ID box, enter the account identifier for the AWS account where you created your IAM user in Step 2.2 Create an IAM user. The account identifier is the 12 digit number in the User ARN. Then, choose Next: Permissions.

Select trusted entitySelect trusted entity

  1. On the Add permissions page, under Policy name, select the policy that you created in Step 2.3 Create an IAM policy (the suggested name in this tutorial was SellingPartnerAPI), and then choose Next

  2. On the Name, review, and create page, enter a Role name, an optional role description, add any custom tags, then choose Create role.

Name, review, and createName, 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:

Role summary pageRole summary page

For more information, refer to Creating a Role to Delegate Permissions to an IAM User in the AWS documentation.

Step 2.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 use 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 to control access to your AWS resources.

  1. Sign in to the AWS Management Console, and then open the IAM console at console.aws.amazon.com/iam.

  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 2.2 Create an IAM user.

  3. On the Permissions tab, choose Add inline policy.

  4. On the Create policy page, select the Visual editor tab, then select Choose a service.

  5. Select the STS service.

    Tip: Enter STS in the search box to narrow your choices.

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

  7. Select AssumeRole.

Select Actions, write, and AssumeRoleSelect Actions, write, and AssumeRole

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

  2. From the Resources section, under Specify role resource ARN for the AssumeRole action, select Add ARN.

  3. In the Add ARN(s) dialog box, enter Account and Role name with path from Step 2.4 Create an IAM role, choose Add, and then choose Review policy.

Add ARNAdd ARN

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

Create policyCreate policy

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

Use the following procedure to verify that the STS policy is attached to your IAM user or role

  1. Install the AWS Command Line Interface (AWS CLI). For detailed instructions on installing the AWS CLI, refer to Getting Started with the AWS CLI in the AWS documentation.

  2. Sign in to the AWS Management Console, and then open the IAM console at console.aws.amazon.com/iam.

  3. Select your IAM user, and then 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. From the AWS CLI, 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 the manged policies that are attached to the specified IAM user:

    aws iam list-attached-user-policies --user-name {{ARN of IAM User}}

  • Retrieve information about the specified managed policy:

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

  • List policies attached to a particular role:

    aws iam list-role-policies --role-name

  • Attach a policy to a role:

    aws iam attach-role-policy --policy-arn arn*:*aws*:*iam*::*aws*:*policy/ReadOnlyAccess --role-name ReadOnlyRole

Step 3. Create a private Selling Partner API application

  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 2. 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 2.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 4. 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 5. Connect to the Selling Partner API

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 Selling Partner API sandbox in the Selling Partner API Developer Guide.

Step 6. 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.