Amazon Selling Partner API Authorization Guide with Ruby on Rails.

A few months back I started working on a new integration where we had to use Amazon’s Selling Partner API for Sellers. I will be covering the Selling partner API authorization flow with Ruby on Rails here.

The question here is that Why are we going to perform an authorization workflow? Let me tell you a bit more about this:
One of my features was to pull orders data from Amazon Seller Central. So we found out that there is a Selling Partner API for orders but to use that API, we have to first get the authorization info such as auth token. And to get that auth token, we have to perform the authorization workflow.
I will be writing soon in another article about using that auth information for pulling orders data from Amazon Seller Central.

So basically we have 2 types of authorization workflows.

• Amazon Seller Central Partner Network authorization workflow (An OAuth authorization workflow initiated from the Amazon Seller Central Partner Network detail page.)
• Website authorization workflow (An OAuth authorization workflow initiated from our own website.)

I went for the second one because I wanted to initiate an authorization flow from my application.

Telling about the steps we have to perform here are:

1. Setting up an Authorize button in our application.
2. Initiating authorization workflow from our application.
3. Processing OAuth info received from Amazon.
4. Requesting an access token for APIs.

Let me tell you about these steps one by one.

Setting up an Authorize button in our application:

We will be setting up an Authorize button in our application which will be clicked to start the authorization flow.
Question: So where would that button take us?
Answer: Here we have to construct an OAuth URI.

Constructing an OAuth URI:

Following things are required to construct an OAuth URI:

• Seller Central URL for our marketplace.
  Amazon sellers can sell in different marketplaces and each marketplace has a marketplace id. So let’s say our marketplace is US, then our seller central URL will be https://sellercentral.amazon.com/. Combine the Seller Central URL with /apps/authorize/consent
  Here we can get our seller central URL based on our marketplace:
  https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-guide/SellingPartnerApiDeveloperGuide.md#seller-central-urls
• Application ID: This is the id of the application which we register on Amazon. This has to be placed as the query parameter.
• State: A state value generated by our application, used to maintain the state between the request and the response. I used SecureRandom.uuid for state. This has to be placed as the query parameter.
• Redirect url: We have to register a redirect url in our Amazon account. Amazon uses that redirect url to send the authorization information back to our application. For the testing purpose, I ran my application with ngrok and registered that url as a redirect url.

Here will be the final OAuth URI:

https://sellercentral.amazon.com/apps/authorize/consent?application_id={application_id}&state={state}

If our application is in draft mode, then we will be adding &version=beta to the end of the OAuth URI.

Initiating authorization workflow from our application:

The next step would be to visit this OAuth URI by clicking the Authorize button and it will take us to the Seller Central. There we can authorize and it will redirect back to our Rails application with the authorization info.

Question: How does it know to redirect back to our Rails application?
Answer: Remember the redirect url which we registered? On successful authorization, Amazon sends us back to that redirect url with authorization information.

So what exactly is sent as authorization info?
Good Question !!!
Here is what we receive:

• state (Remember the state value which we sent as a query parameter)
• selling_partner_id (We definitely need to store it somewhere)
• spapi_oauth_code (This code is used to request an auth token. See the next part.)

So basically on successful authorization, Amazon hits our redirect url with the above query params and we receive this info as params in our Rails application.

Note: This spapi_oauth_code expires after five minutes. Be sure to request an access token before it expires.

Processing OAuth info received from Amazon:

As of now, we have received OAuth info as params in our Rails application.
We first verify the state. How are we gonna do that?

Verifying state:

Remember we generated a state value while constructing the OAuth URI.
We have to store that somewhere so that it can be verified when we receive the authorization information from Amazon.
One way to achieve this could be:

• storing state value in Rails session before hitting the authorize button.
• verifying state value by matching state value in session and the state value received from Amazon.

Requesting an access token for APIs:

The final step here is requesting an access token for APIs.
We hit the Login with Amazon (LWA) authorization server (https://api.amazon.com/auth/o2/token) to get the LWA access token.
We need these to make a successful call.

• grant_type: We set its value to authorization_code for requesting an access token.
• code: This is the spapi_oauth_code which we received as a part of authorization information from Amazon.
• client_id: Part of your LWA credentials. To get this value see https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-guide/SellingPartnerApiDeveloperGuide.md#viewing-your-application-information-and-credentials
• client_secret: Part of your LWA credentials. To get this value, see https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-guide/SellingPartnerApiDeveloperGuide.md#viewing-your-application-information-and-credentials

We make a POST request to https://api.amazon.com/auth/o2/token with the above params. Here is an example of that POST request:

RestClient.post('https://api.amazon.com/auth/o2/token', "grant_type=authorization_code&code=sp_api_oauth_code&client_id=test&client_secret=test")

We get the following info as a successful request response:

{
  "access_token":"Atza|IQEBLjAsAexampleHpi0U-Dme37rR6CuUpSR",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"Atzr|IQEBLzAtAhexamplewVz2Nn6f2y-tpJX2DeX"
}

And finally, we received an access_token. This token will be used to make subsequent calls to Selling Partner APIs.
But I am curious about these other things in the response. What are refresh_token and expires_in?
So the case here is that the access_token is not a long-lived token. It expires for sure and expires_in indicates its expiry interval.
So if it expires, there should be a way to refresh it. Right? Yes, there is a way.

Refreshing the LWA access token:

We hit the Login with Amazon (LWA) authorization server (https://api.amazon.com/auth/o2/token) to refresh the LWA access token.
The client_id and client_secret are the same here as we saw above.
The difference here is:

• grant_type: We set its value to refresh_token for refreshing an access token.
• refresh_token: This is the refresh token that we received in the above call.

We make a POST request to https://api.amazon.com/auth/o2/token as follows:

RestClient.post('https://api.amazon.com/auth/o2/token', "grant_type=refresh_token&refresh_token=refresh_token&client_id=test&client_secret=test")

As a successful request, we get the new access_token.

Hope this article helps !!