eBay OAuth Client Library in Python and Best Practices

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__)[0], '..'))

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__)[0], 'config' ,'ebay-config-sample.yaml')

credentialutil.load(config_path)

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)

SDK flow

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

Features

• 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.

Common issues

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.