Specifying OAuth scopes

Each request you make to an eBay RESTful API must be authorized with a valid OAuth access token. Moreover, each access token is created with a set of OAuth scopes that give the token access to different methods and resources.

Every API method is configured to provide access to the resources it touches via one or more scopes. With this, each scope defines:

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

This means the access token you use to authorize a request must be created with at least one of the scopes required by the method you're targeting. If it helps, think of OAuth scopes as the keys you need to use to gain access to the different resources that are touched by the API methods you call.

Access tokens and scopes

When you mint a new access token, 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 when minting new access tokens, refer to the API documentation for each method you call in your application. Then, make sure to 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 keys, or authorization, needed to make a request each method used in your application.

Scopes and grant types

eBay supports two different "grant flows" for creating access tokens, and each grant flow mints a different type of access token:

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

The grant flow you use depends on the scopes required by methods you call in your application.

Application access tokens vs. User access tokens

You can use the client credentials grant flow to mint access tokens only if all the methods called in your application support scopes that allow authorization with an Application access token.

If your application uses any method that requires a User access token, then you must use the authorization code grant flow to mint the access tokens used by your application, and this means you must get consent from the users of your app.

Important! Not all API methods support access via Application access tokens. In general, mainly GET requests support access via Application access tokens. But, if a method supports any scope that allows access via an Application access token, then you can use that scope when minting tokens.

Here is a partial list of scopes that provide authorization with Application access tokens:

  • https://api.ebay.com/oauth/api_scope
  • https://api.ebay.com/oauth/api_scope/buy.guest.order
  • https://api.ebay.com/oauth/api_scope/buy.item.feedS
  • https://api.ebay.com/oauth/api_scope/buy.marketing

If you use a method in your app that does not support a scope that allows access via an Application access token, then you must use the The authorization code grant flow to generate your access tokens.

Scopes and refresh tokens

When creating User access tokens, you must supply a list of scopes in both your consent requests and your refresh token requests. Here, it's imperative that the scopes you use in your refresh token request match those used in the consent request that you used to obtain the refresh token.

Specifying scopes when minting access tokens

If you're calling methods in different APIs (where each API requires a different scope), you'll need to create a list that contains multiple scopes, and use that list in the scope parameter of your OAuth token request.

Collate the list of all the scopes needed by separating each scope with a space, then URL-encode the entire list. This is the string that you need to supply as the value for the scope parameter in your client credentials grant request, or your consent and refresh token requests.

For example, suppose your application uses methods that require the following three scopes:

  • https://api.ebay.com/oauth/api_scope/sell.inventory
  • https://api.ebay.com/oauth/api_scope/sell.account
  • https://api.ebay.com/oauth/api_scope/sell.fulfillment

The string of scopes you need to use with the scope parameter is:

https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.inventory%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.account%20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.fulfillment