The authorization code grant flow is used to create an OAuth User access token.
OAuth client libraries
The processes in this topic describe how to manually get OAuth tokens. To help with this process, eBay offers several client libraries that you can use to quickly implement the minting of OAuth tokens in your applications:
Sequence for getting and using a user access token
The following sequence diagram outlines the authorization code grant flow, where a User access token is minted, then used in an API request:
Sequence diagram for generating a User access token
Getting a new access token for a user through the authorization code grant flow is a two-step process. First get consent from the eBay user to make API calls on their behalf (see Getting user consent), and then generate the User access token for each user (see Exchanging the authorization code for a User access token).
Getting user consent
This topic covers user consent, the first step you must take to get User access token for a specific user.
About user consent
If your eBay application acts on the behalf of an eBay user, your application must obtain the user's consent before it can make requests that access and update that user's confidential resources.
After gaining the eBay user's consent, make an authorization code grant request to mint a new User access token, a token that carries a user's authorization to let your application access the user's eBay account data.
Configuring the consent request
You need to configure two parts of the redirect URL:
- Setting the target endpoint
- Configuring the HTTP query parameters
Setting the target endpoint
The eBay Sandbox and Production environments host Grant Application Access pages on different servers. The following table lists the supported endpoints:
OAuth token-request endpoints
|
Environment
|
Endpoint (HTTP method + URL)
|
| Sandbox |
GET https://auth.sandbox.ebay.com/oauth2/authorize |
| Production |
GET https://auth.ebay.com/oauth2/authorize |
Configuring the HTTP query parameters
Set the following query parameters to configure your consent request:
Consent Request URL Query Parameters
| Query Parameter |
Description |
|
client_id
|
The client_id value for the environment you're targeting.
Occurrence: Required
|
|
locale
|
The locale parameter to localize the OAuth consent page for the marketplace you're targeting. For example, set locale=de-DE for Germany. See the Locale Support column of the Marketplace ID values table for the supported locales.
Occurrence: Optional
|
|
prompt
|
If needed, you can force a user to log in when you redirect them to the Grant Application Access page, even if they already have an existing user session. To do so, set the prompt query parameter to login.
Occurrence: Optional
|
redirect_uri |
The RuName value for the environment you're targeting.
For details, see Getting your redirect_uri value.
Occurrence: Required
|
|
response_type
|
Set to "code" to have eBay generate and return an authorization code.
Occurrence: Required
|
|
scope
|
A list of OAuth scopes that provide access to the resources used by your application.
For details, see Using OAuth to access eBay APIs
Occurrence: Required
|
|
state
|
An opaque value used by the client to maintain state between the request and callback.
The authorization server returns the same value supplied in the request when it redirects the user-agent back to the client's accept URL. While the state value is optional, we recommend you supply this value and use it to prevent cross-site request forgery, as described in Section 10.12 of the OAuth spec.
Occurrence: Optional
|
The consent request
You obtain user consent via your application's Grant Application Access page, a custom page that asks the user to grant your application the permissions it needs to access the user's eBay account resources.
From your application, direct the user to your application's Grant Application Access page using an HTML redirect that we call the "consent request."
The following consent request is an HTML redirect that targets the Sandbox (the example has been wrapped for readability):
/* URL redirects a user to the application's Grant Application Access page */
GET https://auth.sandbox.ebay.com/oauth2/authorize?
client_id=<app-client-id-value>&
locale=<locale-value>& // optional
prompt=login // optional
redirect_uri=<app-RuName-value>&
response_type=code&
scope=<scopeList>& // a URL-encoded string of space-separated scopes
state=<custom-state-value>& // optional
This HTML request redirects a user to your application's Grant Application Access page. If they consent to the conditions outlined on the page, the redirect returns the user to your application, and the redirect back to your application contains an authorization code.
The Grant Application Access lists the permissions your app needs to access and modify the specific confidential resources that are in your application's control. The list of permissions presented on the Grant Application Access page, and the full list of permissions to which the third-party must consent, is determined by the list of scopes supplied in your permissions grant request.
The list of permissions your app needs to access the eBay APIs determined by the list of scopes supplied in your permissions grant request. The more scopes you include in your permissions grant request, the more permissions the user needs to consent. To trim the list of permissions that the user must consent to, supply only the scopes required to access the methods used in your application, and leave out any scopes that signal access to resources that your application doesn't use.
The Grant Application Access page
The Grant Application Access page displays information about the items you're asking the user to grant access permission for your application. The page contains an Agree and Continue button that the user can click to indicate consent (it also contains a Not now button to indicate denial).
The Grant Application Access page has several links that provide information about the grant request and links that forward the user back to the seller's application. The seller configures much of the links and content on this page through their eBay Developer Program account. (See Getting your redirect_uri value for more details.)
An example Grant Application Access page
The consent request
If the user grants consent by clicking the "I Agree" button on the Grant Application Access page, eBay redirects them back to the seller's Accept URL page (configured with the seller's RuName). The redirect back to your application includes an authorization code , which indicates the user's consent.
/* The redirect to your Accept URL page with the appended authorization code and state value */
https://www.example.com/acceptURL.html?
state=<client_supplied_state_value>&
code=v%5E1.1% ... NjA%3D&
expires_in=299
The example above shows how the authorization code value is returned in the code parameter. The authorization code is tied a single user and you exchange the code for a User access token that is also tied to that user.
If you supplied a state parameter in your consent request, it is also returned in the redirect URL. eBay highly recommends you use this parameter to check for cross-site request forgery (CSRF) attacks.
About the authorization code
The authorization code returned from the authorization code grant is a single-use token that can be used only to retrieve an access token. You cannot use the authorization code to make API requests.
In addition to the code value, the response URL also contains an associated expires_in value that defines the number of seconds the authorization code is valid. Use the authorization code before it expires to obtain a User access token that you can use to make API requests on the user's behalf.
For details, see Exchanging the authorization code for a User access token.
Exchanging the authorization code for a User access token
When a user grants your application the authorization to take action on their behalf, eBay returns an authorization code that contains the user's consent for the specified scopes. Use the authorization code in a POST request that's commonly known as an authorization code grant request. This request gets a User access token and its associated refresh token.
The authorization code is a maximum of 1024 characters in length. Do not store this value, instead use the value only as a run-time parameter that's passed directly to the authorization code grant.
Configuring the request
You need to configure three parts of a client credentials grant request:
- Setting the target endpoint
- Configuring the HTTP request headers
- Configuring the request payload
Setting the target endpoint
The endpoint you use depends on the environment you're targeting:
OAuth token-request endpoints
|
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
authorization_code.
-
Set redirect_uri to the RuName value assigned to your application and the environment you're targeting.
For details, see Getting your redirect_uri value.
-
Set code to the URL-encoded authorization code value returned to you by eBay when the user granted their consent.
For details, see Getting the third-party's consent.
Tip:The authorization code returned by eBay is URL-encoded. This value must be URL-encoded when you pass the value in the code parameter of the authorization code grant request. However, if the method you use to make the request URL-encodes the values you pass, then you must URL-decode the authorization code before using it the authorization code grant request.
The authorization code grant request
The authorization code grant is a request that mints a new User access token. Use the token to make requests to API methods that match the scopes configured into the access token.
Configure your request using the following call specifics:
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=authorization_code
code=<authorization-code-value>
redirect_uri=<RuName-value>
Example cURL request
The following command shows how to configure the authorization code grant request with cURL (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=authorization_code&
code=v%5E1.1%23i%5E1%23f% ... 3D%3D&
redirect_uri=Davy_Developer-DavyDeve-DavysT-euiukxwt'
Response containing the User access token
When you issue the authorization code grant request, eBay returns a JSON object containing the fields shown here:
{
"access_token": "v^1.1#i^1#p^3#r^1...XzMjRV4xMjg0",
"expires_in": 7200,
"refresh_token": "v^1.1#i^1#p^3#r^1...zYjRV4xMjg0",
"refresh_token_expires_in": 47304000,
"token_type": "User Access Token"
}
Use the access token to authorize your API requests.
Because this example targets the Sandbox environment, this access token can be used to make API calls to only the Sandbox. To make requests to the Production environment, repeat the token-generating process using the Production environment values (the OAuth credentials, RuName, and URLs) in each of the token requests you sent to eBay.
About the User access token
The expires_in value returned with the newly-minted User access token indicates the number of seconds that token is valid.
In the example above, the token remains valid for 7,200 seconds (2 hours) from the time it was generated. After the token expires, you will need to renew it using the supplied refresh token.
The refresh token
While User access tokens are short-lived, the associated refresh_token is a long-lived value that you can use to update an expired User access token. This means you do not have to get the user's consent each time you need a new User access token.
To update the access token after it expires, see Using a refresh token to update a User access token.
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:
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:
- Setting the target endpoint
- Configuring the HTTP request headers
- Configuring the request payload
Setting the target endpoint
The endpoint you use depends on the environment you're targeting:
OAuth token-request endpoints
|
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.
