These client libraries reduce the amount of code application developers have to write to get OAuth access tokens. In this article, I focus on detailing the features of the Python client SDK library. I show how to set up and use this library, as well as offer best practices on how to use OAuth tokens.
For detailed information on eBay OAuth tokens, please refer to our standard documentation.
First, to help you effectively use the SDK, let’s have a quick review of eBay OAuth tokens. If you are already familiar with eBay OAuth token types and scopes, please skip ahead to the Getting the SDK Up & Running section later in this document.
Types of OAuth tokens
As indicated by our developer documentation, eBay provides OAuth tokens in two grant flows: client credentials flow and authorization flow.
Application Access Token
Represents an application
Mint access tokens with the Client Credentials Grant flow
User Access Token
Represents an application and an eBay user
Mint access tokens with the Authorization Code Grant flow
The expiration time is determined when token is minted.
OAuth token scopes
In the API Reference documentation, each API method page indicates both the grant type of the token required to make a call to the method and the scope that you must use when you create an access token to call the method.
Below is a section from the getItemFeed API reference. This section indicates that in order to make a getItemFeed API call, you must use an access token obtained via the client credentials grant flow and include the "https://api.ebay.com/oauth/api_scope/buy.item.feed" scope when generating the OAuth token:
Not all scopes are available for an application. For example, to make Feed API calls, your application must be must be configured with the "https://api.ebay.com/oauth/api_scope/buy.item.feed" scope.
To find out the scopes that are available to your application, log into developer.ebay.com, navigate to your “Application Access Keys” page, and click the “OAuth Scopes” link. You should see a list of available scopes, like this:
Getting the SDK up and running
This SDK is written in Python 2, and you must use this environment to use the SDK. Because this is an open source project, please feel free to upgrade the SDK to Python 3.
1. Clone the repo and run the command below to install all dependent components:
$ pip install -r requirements.txt
2. Configure the file ebay-config-sample.yaml (under /test/config) with your application information, as outlined here:
3. If you are running the test script GetUserAccessToken.py that comes with this SDK:
Download the latest Chromedriver for your OS here. Place Chromedriver in the /test directory.
Configure “ebay-config-sample-user.yaml” with your application information and “test-config-sample.yaml” (under /test/config) with your eBay user ID and password.
Steps and code snippets for using the SDK
1. Import oauth2api, credentialutil, and environments:
import os, sys
sys.path.insert(0, os.path.join(os.path.split(__file__), '..'))
from oauthclient.oauth2api import oauth2api
from oauthclient.credentialutil import credentialutil
from oauthclient.model.model import environment
2. Define the path of your application configuration file (i.e. ebay-config-sample.yaml), then load the application information. For example:
config_path = os.path.join(os.path.split(__file__), 'config' ,'ebay-config-sample.yaml')
3. Declare the scopes need for your OAuth access token using a list (refer to “OAuth Token Scope” section above on how to define proper scope), and be sure you don’t use an incompatible scope (refer to “Common Issues” section below):
app_scopes = ["https://api.ebay.com/oauth/api_scope", "https://api.ebay.com/oauth/api_scope/buy.item.feed"]
4. Create an instance of oauth2api:
oauth2api_inst = oauth2api()
5. Call any method within oauth2api using the instance:
app_token = oauth2api_inst.get_application_token(environment.SANDBOX, invalid_app_scopes)
signin_url = oauth2api_inst.generate_user_authorization_url(environment.SANDBOX, app_scopes)
user_token = oauth2api_inst.exchange_code_for_access_token(environment.SANDBOX, code)
user_token = oauth2api_inst.get_access_token(environment.SANDBOX, user_token.refresh_token, app_scopes)
Getting Application Access Token—Client Credentials Grant flow
Getting User Access Token—Authorization Code Grant Initial Flow
Getting User Access Token—When User OAuth Access Token Expired
This SDK accepts configuration files in both JSON and YAML formats. Please refer to the sample template in the /test/config folder.
To avoid caching user information, this SDK generates authorization URLs that forces the user to log in each time. This is accomplished by using the prompt=login parameter.
Debug OAuth-related issues within your application with the eBay_Oauth_log.txt log file.
Please read the Best Practices Info. Also, pay attention to the following common token or scope concerns:
Do not discard your OAuth token after a one-time use. API calls to retrieve an OAuth token are rate-limited per application. To avoid hitting your call limit, cache and re-use tokens until expiration time.
Do not refresh an OAuth User access token with different or new scopes; you must use the exact same scopes that you used to get the original User access token in the Authorization Code Grant flow.
When making a get_access_token call to refresh a User access token, make sure the list of scopes indicated in the call request is the same as or a subset of the scopes given in the original Auth Code Grant request.
Scopes can be user-specific or application-specific. Do not input an incompatible scope when retrieving an OAuth token. For example, if you call get_application_token with a user specific scope, the call will respond with an error.