Getting user consent

This topic covers user consent, the first step you must take to get User access token for a specific user.

Subtopics

If your eBay app acts on the behalf of an account owner, 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 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 app 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:

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

The endpoints above provide for responsive design and should be used by all applications for their consent requests. The older URLs published by eBay will continue to be supported, but are not recommended because they support only desktop systems.

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.

For details, see Getting your OAuth credentials.

redirect_uri

The RuName value for the environment you're targeting.

For details, see Getting your redirect_uri value.

response_type Set to "code" to have eBay generate and return an authorization code.
scope

A list of OAuth scopes that provide access to the resources used by your application.

For details, see Specifying OAuth scopes.

state

(optional) 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.

prompt

(optional) 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.

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 app the permissions it needs to access the user's eBay account resources.

From your app, 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>&
    redirect_uri=<app-RuName-value>&
    response_type=code&
    state=<custom-state-value>&
    scope=<scopeList>&   // a URL-encoded string of space-separated scopes
    prompt=login

This HTML request redirects a user to your application's Grant Application Access page. If they consent to the conditions outline on the page, the redirect returns the user to your application, and the redirect back to your app 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 button that the user can click to indicate consent (it also contains a "Go Back" 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 app. 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
An example Grant Application Access page

The consent request response

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 app includes an authorization code , which contains 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 response 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 can 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.