eBay oauth token and refresh tokens

Question

been struggling for couple of days with eBay token authentication. I am finding it hard to understand how to fetch new tokens, after signing up for a developer program account, I requested the key-set and got them, afterwards I grant access on Auth'n'Auth token which promises to last for 18 months, and yes the token works only on Trading, Shopping and Finding api.

But when you need to perform Buy, Sell and Commerce api's you have to obtain oauth tokens. And you can do the so called "Single User app" style and signin on oauth from User Token Tool, and get an oauth with 2 hours expiry.

Later on the token expires and you kinda lose the access to the api's mentioned above. I tried fetching tokens from Trading > Get session ID, Trading > Fetch token, but after providing session id to Fetch token it says: "The end user has not completed Auth & Auth sign in flow." while there is a valid 18 months token, it keeps returning this error.

Is there any example article on this, which anyone might have read or wrote?

Answer 1

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!