Specifying OAuth scopes

The scopes assigned to your application allow access to different API resources and functionality.

Subtopics

Access tokens and scopes

Think of OAuth scopes as the keys that give you access to the different methods and resources of an API. The OAuth tokens you use to authorize your requests must have the keys required by the methods and resources you are trying to access.

No matter which type of OAuth access token you generate, you must supply the set of scopes, or keys, for the functionality you'll be accessing with the generated token.

In another way, a valid OAuth token can successfully authorize a request only if the token was generated with the scope required by the target method.

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 different API methods, resources and functionality.

You can view the sets of scopes assigned to your application through the Application Keys page in the Developers Program website.

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

Figure showing link to screen of OAuth scopes

Scopes and access

Each scope assigned to a set of credentials defines:

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

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 for your application, refer to 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

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

Collate the list of all the scopes needed by separating each scope with a space, then URL-encode the list. Supply the enter string as the value for the scope parameter in your request to the token server.

Example scope string

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

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

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

The URL-encoded string of scopes you need to supply 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

Getting the list of scopes assigned to your application

When you create a set of application keys, a set of scopes is assigned to those credentials.

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 for either the Sandbox of 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:

    A sample request

    This displays the drop-down Get a Token from eBay via Your Application.

  3. Click the Get a Token from eBay via Your Application drop-down and, after configuring an RuName, an RuName box similar to the following displays:

    The Get a Token dialog box

  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

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 in your application.

Application access tokens vs. User access tokens

If all the calls in our application require just an Application access token, then you can use the client credentials grant to mint the tokens for the app.

However, if any of the methods in your application require a User access token, then you must use the authorization code grant and refresh token flows to mint your tokens. This flow requires you 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.