Migrate seller authorizations from MWS to SP-API

by Supriya P., Solutions Architect, Selling Partner Developer Services | May 26, 2022

Update October 2, 2023 - This post has been updated to remove outdated AWS IAM ARN and/or AWS Signature Version 4 information.

In a typical migration workflow moving from Amazon MWS to Selling Partner API, you create a hybrid SP-API application which calls both MWS and SP-API. If you want to make calls only to SP-API, sellers must re-authorize you to call SP-API on their behalf. With the Selling Partner API for Authorization, you can migrate these calls and eliminate the need to request authorization from sellers for your hybrid SP-API application. You still retain access to your MWS application with a hybrid application. When you convert your hybrid application to a full SP-API application, you can no longer make calls to MWS.

This blog post shows you how to use Postman to call the Authorization API and migrate your seller authorizations to SP-API.

Note: The Authorization API can help you eliminate authorization requests when migrating existing MWS authorizations to SP-API, but it does not eliminate authorization requests after adding new roles. If you add a new role to your application, sellers must re-authorize your app with the updated roles.

Overview

You can migrate an Amazon MWS authorization to a Selling Partner API application in two main tasks:

1. Get the LWA authorization code: (Step 1, Step 2) Call the getAuthorizationCode operation to return the Login with Amazon (LWA) authorization code for an existing Amazon MWS authorization. The getAuthorizationCode operation is a grantless operation that you can call without explicit authorization from a selling partner.
2. Exchange the LWA authorization code for an LWA refresh token: (Step 3) Call the LWA authorization server to exchange the LWA authorization code for an LWA refresh token. Upon receiving the refresh token, your application is authorized to make calls to Selling Partner API operations on the seller's behalf.

The Authorization API uses a grantless LWA exchange that you can call without an explicit authorization from a selling partner. This means that when you request a Login with Amazon access token prior to calling a grantless operation, you don't need to provide a refresh token. Instead, you use the scope parameter to provide the scope of the LWA authorization grant. If you use a generated Java SDK to call grantless operations, use the withScopes parameter to set one or more scopes for the LWA authorization grant when you configure your LWA credentials. For the Authorization API, you must use the scope parameter as SCOPE_MIGRATION_API.

Note: If you have multiple regional MWS developer-ids, you must associate all of them with your hybrid Selling Partner application, and re-publish your application before you can migrate authorizations from individual MWS developer-ids to your hybrid Selling Partner application.

Tutorial

The following tutorial walks you through using Postman to call the Authorization API and migrate your seller authorizations to SP-API.

Prerequisites

To complete this tutorial, you need the following prerequisites :

• A hybrid SP-API app published to the Amazon Selling Partner Appstore.
• Access to and familiarity with making API calls in Postman.

First, follow steps 1 through 3 to get the LWA authorization code.

Step 1. Generate a grantless LWA access token

1. In Postman, make a POST call to https://api.amazon.com/auth/o2/token
2. On the Body tab, select x-www-form-urlencoded. Add the following values:
   • grant_type: client_credentials
   • scope: sellingpartnerapi::migration
   • client_id: Part of your LWA credentials received after you register your app. To get this value, refer to Viewing your developer information.
   • client_secret: Part of your LWA credentials received after you register your app. To get this value, refer to Viewing your developer information.
3. Choose Send.

The response returns the grantless LWA access token that you can use to authenticate your SP-API call. For the Authorization API, the access token starts with Atc|****************************. Refer to the following image for an example.

Step 2. Make a call to the Authorization API endpoint

1. Import the Authorization model to your Postman workspace.
2. Make a GET call to baseUrl/authorization/v1/authorizationCode
   Note: The baseUrl can be SP-API production endpoints or SP-API sandbox endpoints.
3. Choose the Headers tab, and use the following key value pair to add the access_token value that you received in Step 1: x-amz-access-token: Atc|********************

4. Choose the Params tab, and add the following values,
   • sellingPartnerId: This must be the seller ID (string) of the seller who authorized your application on the Amazon Selling Partner Appstore and also for whom you are migrating the MWS Authorization to SP-API.
   • developerId: This must be the developer ID that you were provided when you registered your application in Developer Central. Also, the developer ID should be the one which was used to register that specific MWS authorization. Note: The authorization is specific to regions. If you have three different developer IDs in three different regions NA/FE/EU, you must run the Authorization API for each region.
   • mwsAuthToken: The MWS Auth Token that was generated when the seller authorized your application on the Marketplace Appstore.
5. Choose Send.

The response returns an LWA authorization code as seen in the following image.

Step 3. Exchange authorization code for an LWA refresh token

The authorization code expires after five minutes so you must first exchange it for a long lived LWA refresh token.

1. In Postman, make a POST call to https://api.amazon.com/auth/o2/token
2. On the Body tab, select x-www-form-urlencoded and specify following values:
   • grant_type: authorization_code
   • code: The LWA authorization code that you received in Step 2. Make a call to the Authorization API endpoint
   • client_id: Part of your LWA credentials received after you register your app. To get this value, refer to Viewing your developer information.
   • client_secret: Part of your LWA credentials received after you register your app. To get this value, refer to Viewing your developer information.
   • redirect_uri: The redirect URI for your application.
3. Choose Send.

Once you obtain the LWA refresh token, save it and use this to exchange it for an LWA access token starting with Atza|************* (For steps, refer to Step 1). This access token must be included in the header to make calls to all the other SP API calls. Note that an LWA access token expires one hour after it is issued.

You have now migrated your existing sellers MWS authorizations successfully to SP-API!

If you want to automate the process to obtain the authorization code using the Authorization API, you can do so by generating a Java SDK for this API. Refer to Automate your SP-API calls using Java SDK for detailed steps to generate a Java SDK for SP-API.

Conclusion

In this blog, you learned how to migrate your seller authorizations from MWS to SP API seamlessly without your sellers manually re-authorizing you. In the walkthrough, you used Postman to call the Authorization API and migrate your authorizations. For more information on Authorization API, refer to the Authorization API Use Case Guide. For troubleshooting tips for calling the Authorization API, refer to the SP-API Errors Frequently Asked Questions. For more questions on migration, refer to the SP-API Migration Frequently Asked Questions.

👍

Have feedback on this post?

If you have questions or feedback on this post, we'd like to hear from you! Please vote and leave a comment using the tools at the bottom of this page.

Subscribe to updates via RSS feed.