OAuth scopes grant your application access to the different methods and resources. The OAuth tokens you use to authorize your requests must have the OAuth scope 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 for the functionality you will 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 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.
When using the Identity API to mint tokens, the scopes belonging to an application keyset are passed in through a scope query parameters. See the The client credentials grant flow and The authorization code grant flow for detailed information on how to pass in the scopes through the scopes query parameter.
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 of Production environment:
- Log in to the eBay Developer Program and navigate to Your Account > Application Keys.
-
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.
-
Under the Get a Token from eBay via Your Application heading, after configuring an RuName, an RuName box similar to the following displays:
-
To view a complete sample request, click the See all link.
Copy from the sample the full value of the
scopeparameter to get a list of scopes assigned to your application. - URL-encode the
scopevalue 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 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 The authorization code grant flow is used to mint user tokens which are used for methods that do 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