Using a refresh token to update a User access token

When you mint a new User access token, the access token is returned along with a refresh token, which you can use to renew the User access token for the associated user. A refresh token request mints an access token that contains the same authorization properties as the original access token.

About refresh tokens

For security, a User access token is short-lived. However, a refresh token is long-lived and you can use it to renew a User access token after the token expires. The benefit is that you don't need to get the account-owner's consent each time you need to renew their User access token.

The sequence for using a refresh token

The application can make API calls on the eBay user's behalf as long as the access token associated with their account is valid. If the access token is expired, renew the User access token using the following logic:

Configuring the refresh token request

You need to configure three parts of a refresh token request:

• The target endpoint
• The HTTP request headers
• The request payload

Setting the target endpoint

The endpoint you use depends on the environment you're targeting:

Configuring the HTTP request headers

Set the following HTTP request headers:

• Content-Type – Must be set to: application/x-www-form-urlencoded

• Authorization – The word Basic followed by your Base64-encoded OAuth credentials (<client_id>:<client_secret>)

  For details, see Generating your Base64-encoded credentials.

Configuring the request payload

Format the payload of your POST request with the following values:

• Set grant_type to refresh_token.

• Set refresh_token to the refresh token value returned from the authorization code grant request.

  To get a refresh token, you must mint a new User access token.
  This process starts with Getting the user's consent.

• Set scope to the same URL-encoded list of scopes that you used in the original consent request.

  For details on scopes, see Using OAuth to access eBay APIs.

The refresh token request

To update an expired User access token using a refresh token request, configure the target URL, HTTP headers, and request payload as shown here:

  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:
    grant_type=refresh_token
    refresh_token=<your-refresh-token-value>
    scope=<scopeList>   // a URL-encoded string of space-separated scopes

Example cURL request

The following command shows how to configure the refresh token request with cURL (the code has been wrapped for readability):

curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic RGF2eURldmUtRG2 ... ZTVjLTIxMjg=' \
  -d 'grant_type=refresh_token&
      refresh_token=v^1.1#i^1#p^3# ... fMSNFXjEyODQ=&
      scope=https://api.ebay.com/oauth/api_scope/sell.account%20
            https://api.ebay.com/oauth/api_scope/sell.inventory'

Response containing the updated User access token

When you issue the refresh token request, eBay mints a fresh access token and sends it back in a JSON response similar to the following:

  {
    "access_token": "v^1.1#i ... AjRV4yNjA=",
    "expires_in": 7200,
    "token_type":"User Access Token"
  }

About refresh tokens

You can continue to use the refresh token to mint new User access tokens for a specific user, as long as the refresh token associated with their account is valid. Note, however, that if the long-lived refresh token expires, or if you update the scopes needed by your app, you must update both the access token and the refresh token, starting with Getting the third-party consent.

While you can track the lifespan of each access token and refresh them before they expire, the amount of processing and storage needed to track the lifespans of multiple tokens often outweighs the processing needed to refresh a token once it has expired. For this reason, it is best to refresh each access token after it expires (and you receive an "Invalid access token" error), rather than trying to renew each token before it expires.