OAuth access tokens
All eBay REST interfaces use OAuth 2.0 access tokens for application authentication 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.
The process of getting and using OAuth tokens might at first seem complicated. However, the steps are straight-forward once you understand the principles:
- Gather the values you need to get an access token from eBay.
- Send a token request to eBay to ask for a new access token.
- Use the token to authenticate your REST requests.
- Update the access token after it expires.
There are two types of access tokens, User tokens and Application tokens.
For the most part, Application tokens are general-use tokens that can be used for actions that don't require a high level of authorization (such as getting various information from the system).
User tokens, on the other hand, provide access to more powerful interfaces because they contain a grant from the user that authorizes access to their user data. Because of the sensitivity of the information that User tokens allow you to access (and the transactions they enable), the process and requirements needed to get a User token are more involved than the process for getting an Application token. Specifically, the user must grant your application the authorization needed to call the more restrictive interfaces.
Tip: You must have an active eBay Developer Program account to get the credentials needed to create OAuth tokens. For details, see: Creating an eBay Developers Program account.
Getting access tokens for your app
If you know what you're doing, follow these links to go straight to the procedures for generating tokens:
If you don't know the type of token you need (or if you just want to know more about tokens), read the rest of this topic by clicking the drop-down link below.
You can use one of two different access token types to authenticate the calls your application makes to the eBay APIs:
- Application tokens
- User tokens
Each token type provides for different levels of security and access, and you must use a different procedure to generate each type of access token. The token type you use depends on the architecture of your application and the role of the users who will be interacting with your app.
Access Token Types
Application tokens are general-use tokens that give access to non-intrusive eBay operations. For example, many
You must employ a User token to call "low-level" methods that access or modify user data and accounts. For example, consider an application that acts upon the eBay accounts of third-party users during an eBay transaction.
To get a User token, the users of your app must grant your application the permissions it needs to act upon their behalf. Each User token contains the set of scopes for which the user has granted their permission.
Check the scope requirements of each of the eBay methods you plan to use in your application, and include those scopes in your requests to generate User tokens.
It should be noted that not all architectures require the use of User tokens for low-level access; some application architectures are well-suited for the level of authorization provided by an Application token. Consider an application where the user is also the application owner and the all operations of the application modify only the data owned by the user. A user grant in this scenario makes little sense. That said, the eBay interfaces are designed to fit the requirements of a broad set of applications and the scoping requirements needed by the more powerful interfaces require you employ User tokens to access the methods that retrieve and modify user information and accounts.
More on access tokens
The eBay access token types are based on OAuth 2.0 client types and client profiles. eBay Application tokens pair a public client with a web application profile, while eBay User tokens pair a public client with a user agent profile.
OAuth 2.0 defines the following two client types:
A confidential client is an application that's able to keep OAuth credentials secure (and confidential) from the world at large. It is a "first-party" application in that only trusted users have access to the app internals, which is where token values might be stored. An example of such an app is a web application in which only the administrator has access to the server, and thus the OAuth credentials.
Contrast this to a public client application that is unable to keep credentials secure. Think of a mobile application that can be downloaded and used by many. You wouldn't want to store confidential credentials within this type of third-party application.
In addition to client types, the OAuth spec also defines several types of client profiles, including the web application profile and the user-agent based application profile. Typically, a web application is a confidential client that runs on a server and is accessed by a browser, while a user agent app is downloaded so it can run locally on a user's device. Mobile apps usually fall into this profile. It's also not unusual for a user-agent app to be accessed both from a server by a browser and directly through a native app.
In some scenarios, OAuth Application tokens pair a confidential client with a web application profile. This use case provides for tokens to be used with first-party applications, where the application users are implicitly trusted to access the interfaces targeted by the application's requests. The most common scenario for this type of Application token arises when the owner of an application operates as the application's user.
See the following topics for details for generating the different types of tokens: