We support two methods for authorizing the calls you make to the eBay APIs:

• OAuth—eBay APIs use the OAuth 2.0 protocol for application and user authorization. OAuth is the industry standard for assuring your online transactions are secure. You must provide a valid access token for each request you make to the eBay interfaces. OAuth access tokens verify to eBay that a request is coming from a valid application and that the application has the user's authorization to carry out the requests. You can also use OAuth tokens with eBay Traditional APIs.

  Important: If you use Traditional APIs like the Trading API, we recommend that you use OAuth, but eBay's older Auth'n'Auth process is still available for older applications.

  The OAuth scopes assigned to your application allow it to access specific API resources and methods. A valid OAuth token can successfully authorize a request only if the token was generated with the scope required by the target method.

  You can see the OAuth scopes for your application in Application Keys.

• Auth’n’Auth—The authentication and authorization technology used by eBay Traditional APIs.

The assignment of scopes

Once signed in to the Developers Program, you can generate application keys for both the Sandbox and Production environments.

When generated, each set of application keys is assigned a set of scopes where each scope gives the application access to different API methods, resources, and functionality.

You can view the sets of scopes assigned to your application keyset through the Application Keys page in the developer portal.

Click the OAuth Scopes link that is displayed in the lower-right of the image below to get the list of scopes for your application:

Scopes and access

Each scope assigned to an application keyset determines:

• The set of resources that can be accessed with the scope.
• The set of operations that can be performed with the scope.

The request you use to generate the new token must include a list of scopes that allows access to all the methods you plan to call with the token.

To discover the scopes you need for your application, refer to the OAuth scope section of the API documentation for each method you use in your application. Then, mint your access tokens using at least one of the scopes listed for each method you call. In this way, each access token will contain the authorization needed to make all the requests.

Specifying scopes when minting access tokens

Whichever flow you use to generate OAuth access tokens, you must always supply a valid list of scopes with your request to generate the token.

eBay OAuth access tokens are minted through the OAuth token service. The way you pass scopes depends on the grant flow you use. See The client credentials grant flow and The authorization code grant flow for details.

Getting the list of scopes assigned to your application

When you create a set of application keys, a set of scopes is assigned to your application keyset.

The Developers Program offers a sample request for both the Sandbox and Production environments, and you can use these samples to get a string of the scopes that have been assigned to your application.

To get the list of scopes assigned to your application keyset for either the Sandbox or Production environment:

1. Log in to the eBay Developer Program and navigate to Your Account > Application Keys.

2. Click the User Tokens link that's displayed next to the Client ID of the environment you want to target:

   

   This displays the User Tokens (eBay Sign-In) page.

3. Under the Get a Token from eBay via Your Application heading, after configuring an RuName, an RuName box similar to the following displays:

   

4. To view a complete sample request, click the See all link.

   Copy from the sample the full value of the scope parameter to get a list of scopes assigned to your application.

5. URL-encode the scope value when you send it with your request to the token server.

When you copy the scopes in this manner, you can end up using a larger set of scopes than is needed by your application. The user scopes imply a permission grant, and users must consent to all the permissions your scopes represent before they can use your application.

Be aware, it's possible the Sandbox and Production environments support different sets of scopes for your application. When supplying the string of scopes in your token requests, be sure to match the scopes to the environment you're targeting.

Scopes and grant flows

The eBay token service mints access tokens via two different grant flows:

• Client credentials grant flow mints a new Application access token.

• Authorization code grant flow mints a new User access token.

Each flow uses a different process to generate access tokens, and the grant flow you use depends upon the scopes assigned to the eBay methods used in your application.

The client credentials grant flow is used to mint application tokens, which can be used if the application is accessing or working with resources and data that is not specific to an eBay user. Good examples of methods that require application tokens are metadata or taxonomy calls.

The authorization code grant flow is used to mint user tokens, which are used for methods that post or return data that is specific to an eBay user. There are a lot more methods that require user tokens than application tokens. The OAuth scope section in each method's reference page indicates which tokens are needed for that method.

Scopes and refresh tokens

When creating a User access token, you must supply a list of scopes in your consent request. (See Getting the list of scopes assigned to your application.) For more details, see The authorization code grant flow.

When requesting a refresh token, you can either:

• include an optional scope parameter to supply a list of scopes; or

• include no scope parameter and default to the set of scopes included in the consent request.

eBay APIs use the OAuth 2.0 protocol for application and user authorization. OAuth is the industry standard for assuring your online transactions are secure and you must provide a valid access token for each request you make to the eBay REST interfaces.

OAuth access tokens verify to eBay that a request is coming from a valid application and that the application has the user's authorization to carry out the requests.

Once you obtain a valid access token, use it to authorize a request.

Minting access tokens

The eBay token service generates, or mints, access tokens via two different grant flows:

• Client credentials grant flow mints a new Application access token that you can use to access the resources owned by the application.
• Authorization code grant flow mints a new User access token that you can use to access the resources owned by the user.

The eBay OAuth client libraries

eBay offers several client libraries that you can use to quickly implement the minting of OAuth tokens in your applications:

• OAuth client library for Android
• OAuth client library for C#
• OAuth client library for Java
• OAuth client library for Node.js
• OAuth client library for Python

Implementing OAuth in your applications

The following topics describe how to implement the minting of OAuth tokens using each of the two grant flows:

• The client credentials grant flow
• The authorization code grant flow

Basic <B64-encoded_oauth_credentials>

This topic describes how to mint OAuth access tokens using the client credentials grant flow.

The access token retrieved from this process is called an Application 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:

• OAuth client library for Android
• OAuth client library for C#
• OAuth client library for Java
• OAuth client library for Node.js
• OAuth client library for Python

Sequence for getting and using an application access token

The following sequence diagram outlines the client credentials grant flow, where an Application access token is minted, then used in an API request:

Sequence diagram for generating an Application access token

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:

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

• Set scope to the URL-encoded space-separated list of the scopes needed for the interfaces you call with the access token.

  For details, see Specifying scopes when minting access tokens.

The client credentials grant request

The client credentials grant is a single request that mints a new Application 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=client_credentials
    scope=<scopeList>   // a URL-encoded string of space-separated scopes
		

Example cURL request

The following command shows how to configure the client credentials grant request with cURL:

curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic UkVTVFRlc3...wZi1hOGZhLTI4MmY=' \
  -d 'grant_type=client_credentials&scope=https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope %20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fbuy.item.bulk'

Response containing the Application access token

When you issue a client credentials grant request, eBay returns a JSON object that contains an Application access token, as shown in this response:

  {
    "access_token": "v^1.1#i^1#p^1#r^0#I^3#f^0#t^H4s ... wu67e3xAhskz4DAAA",
    "expires_in": 7200,
    "token_type": "Application Access Token"
  }

To use an access token to authorize an API request, pass the token value in the Authorization HTTP header.

In the above example, the expires_in element is set to 7,200 seconds, meaning this token is valid for two hours from the time it was generated. For continued access after the token expires, you must mint a new token.

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:

• OAuth client library for Android
• OAuth client library for C#
• OAuth client library for Java
• OAuth client library for Node.js
• OAuth client library for Python

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

The eBay Sandbox and Production environments host Grant Application Access pages on different servers. The following table lists the supported endpoints:

Set the following query parameters to configure your 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 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

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.

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

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

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.

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.

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>

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'

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.

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:

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

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

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.

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

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'

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"
  }

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.