Developer HubAPI StatusSupport

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

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 create in Step 3.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 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 Add tags (optional) page, add any desired tags, and then choose Next: Review.

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

Review 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 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 3.4 Create an IAM role.

Record user ARN

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

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 create in Step 3.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 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 policy

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

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.

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 3.2 Create an IAM user. The account identifier is the 12 digit number in the User ARN. Then, choose Next: Permissions.

Select trusted entity

  1. On the Add permissions page, under Policy name, select the policy that you created in Step 3.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 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 page

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

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 use allows you to request temporary AWS access keys that you can use to authenticate your requests to the Selling Partner API. These credentials improve the security of your app as they 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 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 3.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 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 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.

Create policy

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

Updated about 1 month ago