eBay oauth token and refresh tokens

For anyone who struggles, please note the URL in step 4 is different from the URL given on eBay. The URL on eBay begins with https://auth.sandbox.ebay.com/oauth2/authorize, but the URL in step 4 begins with https://signin.sandbox.ebay.com/authorize

This details the OAuth process of the "New Sell" API, not auth 'n' auth or the legacy Trading API. It is also for the sandbox, although the procedure for Production is the same.

Your confusion is not unwarranted. My own experiences with this API flow, along with those of a large portion of the official dev forums, has been stressful. The below details the procedure to generate an oauth irrelevant of whether you are connecting to a single, dedicated, account or multiple user accounts.

There is the official guide, which does explain the whole process, so I'm hesitant to recreate entire guide here. I can provide a summary though (I advise following the below using Postman before attempting through your app):

1. Gather your client ID and Client Secret from here (do not share these publicly)

2. Generate an RuName (Redirect URL Name) from here by clicking "Get a Token from eBay via Your Application" and filling out the form. This form is for building the look of the login page that users will be redirected to allow your application access to their account. The RuName will then appear directly underneath the column header " RuName (eBay Redirect URL name)"

3. Gather the list of scopes you require. Each API endpoint requires an OAuth token with the appropriate scope permissions. The Create or Replace Inventory Item endpoint, for instance, requires the https://api.ebay.com/oauth/api_scope/sell.inventory scope. Figure out what endpoints you will need and go to the API doc for each and find the scope section.

4. The get request now looks like this:

   `https://signin.sandbox.ebay.com/authorize?
   client_id=<your-client-id-value>&
   redirect_uri=<your-RuName-value>&
   response_type=code&
   scope=https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.account%20
   https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.inventory`
   

   It is also recommended you add astate query string, which I have omitted for ease of use, but you should research what they are and why they are recommended for OAuth.

5. This URL in a browser will redirect you to a sign-in page for the user to allow your application access to their account, but only for the scopes in the URL. Dumped from a PHP curl request you will get the redirect URL itself. Important: A sign by the end user is needed even if your application will only have one user. For instance, you have an e-commerce site for a client and you want to send their products to their singular eBay account. You will still need to do this process at least once every 18 months (find out why soon).

6. Once the user has logged in and confirmed, the browser will display a "you can close this window now" page. The authorization code you need for the next step is in the URL of this page as the code query string. If you are developing an application for multiple users and plan to actually have them sign in on this page then you need to configure your app to grab the confirmation response, which will be the aforementioned URL, and extract the code from it. This code is very short-lived. If you are manually retrieving it via a browser you need to progress through the next steps quickly.

7. You now need to perform a POST request to https://api.sandbox.ebay.com/identity/v1/oauth2/token. See the structure below:

   HTTP method:   POST
   URL (Sandbox): https://api.sandbox.ebay.com/identity/v1/oauth2/token
   
   HTTP headers:
   Content-Type = application/x-www-form-urlencoded
   Authorization = Basic <B64-encoded-oauth-credentials> (A base64-encoded value made from your client ID and client secret, separated by colon. For example, in PHP you could generate it with: `base64_encode ("fakeclientid123:fakeclientsecret123")`)
   
   Request body (wrapped for readability):
   grant_type=authorization_code& (literally the string "authorization_code")
   code=<authorization-code-value>& (code retreived in previous step)
   redirect_uri=<RuName-value> (same RuName as earlier)
   

   If successful this request will return something like the below:

   {
       "access_token": "v^1.1#i^1#p^3#r^1...XzMjRV4xMjg0",
       "token_type": "User token",
       "expires_in": 7200,
       "refresh_token": "v^1.1#i^1#p^3#r^1...zYjRV4xMjg0",
       "refresh_token_expires_in": 47304000
     }
   

   There's the oauth token we're after, which will last 2 hours. The second token is a refresh token, which will last ~18 months. Keep this token safe and do not share it, nor hard-code it in your app. From this point onwards your app should perform refresh calls, using this token, to get a new oauth whenever it needs to. Once the 18 months is up, or if the user goes through the "Allow Access" procedure again, you will need to do all of the above to generate a new refresh token. Assuming the API has not changed by that point.

   It is worth noting that the 18 month lifespan is not a normal procedure for OAuth refreshing, which normally should return a new refresh token each time the old one is used.

8. To refresh an oauth:

     HTTP method:   POST
     URL (Sandbox): https://api.sandbox.ebay.com/identity/v1/oauth2/token
   
     HTTP headers:
       Content-Type = application/x-www-form-urlencoded
       Authorization = Basic <B64-encoded-oauth-credentials>
   
      Request body (wrapped for readability):
         grant_type=refresh_token&
         refresh_token=<your-refresh-token-value>&
         scope=https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.account%20
         https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.inventory
   

I hope this helps!

For those who struggles with it - make sure that you are using the code / token encoded.

I almost lost my mind trying to figure out what is wrong because ebay returns the refresh token decoded