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:

• The target endpoint
• 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:

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 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.