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:
Sequence diagram for generating a User access token with a refresh token
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:
Environment |
Endpoint (HTTP method + URL) |
---|---|
Sandbox | POST https://api.sandbox.ebay.com/identity/v1/oauth2/token
|
Production | POST https://api.ebay.com/identity/v1/oauth2/token
|
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.
Note:
The scope parameter is optional. If you do not specify a scope parameter, the default will be the set of scope values included in the consent request. If you do specify a scope parameter, the included scope values must be equal to or a subset of the scope values included in the consent request.
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.
Important! Refresh tokens can be revoked due to various merchant activity on eBay. Specifically, if a seller changes their eBay member log-in name or the password for their eBay account, any active refresh tokens associated with the account will be automatically revoked by eBay. In addition, sellers can choose to revoke a token themselves via their eBay account pages.
If your refresh token gets revoked (or if it expires), then you must redo the consent-request flow in order to get a new access token and refresh token for the associated user.