Using OAuth with the eBay traditional APIs

You can use OAuth access tokens to make requests to several of the traditional eBay APIs.

Subtopics

Note: The eBay "traditional APIs" include the Trading API, the Post Order API, and more. The traditional APIs are the APIs that were implemented and released before we began releasing our RESTful APIs. It is important to note that we still fully support and maintain our traditional APIs.

Authorizing API requests

Before the introduction of the eBay RESTful APIs, all requests to the traditional APIs required you authorize your requests with a system that's known as Auth'n'Auth (which stands for authentication and authorization).

As you begin to use the new eBay RESTful APIs, you'll find the APIs require you to use OAuth access tokens for authorization. This can be confusing because it appears that you need to use two separate authorization mechanisms if you want to use all of the eBay APIs.

Standardizing on OAuth

The good news is that we're retooling some traditional APIs to support OAuth as an authorization mechanism. With this upgrade, you can now use OAuth tokens to authorize the requests you make to the following traditional APIs:

  • Trading API
  • Post Order API
  • Business Policy Management API

The above APIs now support OAuth User access tokens for authorization, and you can generate these OAuth tokens through a process known as the "authorization code grant flow."

Like Auth'n'Auth, the OAuth authorization code grant flow involves delegation via a user consent .With this, your app must redirect the user to a Grant Access Page so they can consent to the eBay terms and conditions of use. And now that some traditional APIs support OAuth for authorization, you can get a user's consent just once, after which you can call any of the APIs that support OAuth.

Note: We plan to add more traditional APIs to the list of those that support OAuth. As we do, we'll update this document with the details of how to authorize your requests to the APIs that support OAuth.

OAuth scopes and the traditional APIs

Each OAuth User access token is associated with one or more "scopes" that gives each token the power to make requests to one or more APIs (different APIs can require you to use different scopes for access). We recommend that you use the following set of scopes when you create the User access tokens for use with the traditional APIs:

OAuth scopes
Scope Description
https://api.ebay.com/oauth/api_scope View public data from eBay
https://api.ebay.com/oauth/api_scope/sell.marketing View and manage your eBay marketing activities, such as ad campaigns and listing promotions
https://api.ebay.com/oauth/api_scope/sell.inventory View and manage your inventory and offers
https://api.ebay.com/oauth/api_scope/sell.account View and manage your account settings
https://api.ebay.com/oauth/api_scope/sell.onboarding Share your merchant profile data with eBay
fulfillments https://api.ebay.com/oauth/api_scope/sell.fulfillment View and manage your order

Tip: While you might not need this complete list of scopes to authorize all the calls you make in your application, we recommend you include this list of scopes so that your access tokens have the most flexibility as you move forward with your application development.

For complete details on generating User access tokens, see The authorization code grant flow.

Implementing OAuth instead of Auth'n'Auth

This section details how to use OAuth instead of Auth'n'Auth in the supported traditional APIs.

Using OAuth in Trading API requests

To make a Trading API request using OAuth:

  1. Remove the RequesterCredentials field and its associated value from the request payload (this field is used to pass your Auth'n'Auth credentials).
  2. Add the X-EBAY-API-IAF-TOKEN HTTP request header to the request and populate its value with a valid User access token.

Here's an example of the HTTP request headers and the associated payload needed for a GetCategories request:

HTTP Headers
    X-EBAY-API-IAF-TOKEN              <UserAccessTokenValue>
    X-EBAY-API-CALL-NAME              GetCategories
    X-EBAY-API-SITEID                 0
    X-EBAY-API-COMPATIBILITY-LEVEL    1085

Request Payload 
    <?xml version="1.0" encoding="utf-8"?>
    <GetCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
      <CategorySiteID>0</CategorySiteID>
      <DetailLevel>ReturnAll</DetailLevel>
      <LevelLimit>1</LevelLimit>
    </GetCategoriesRequest>

An example SOAP request

POST https://api.sandbox.ebay.com/wsapi?callname=GetUser&version=1085&siteid=0 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8

X-EBAY-API-IAF-TOKEN: v^1.1#i^1#I^3#p^3#f^...r^0#t^H4s
Content-Length: 434
Host: api.sandbox.ebay.com

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
           xmlns:urn="urn:ebay:apis:eBLBaseComponents">
  <soapenv:Body>
    <urn:GetUserRequest>
      <urn:Version>1085</urn:Version>
      <urn:MessageID>Soap call - OAuth Token in trading</urn:MessageID>
      <urn:DetailLevel>ReturnAll</urn:DetailLevel>
    </urn:GetUserRequest>
  </soapenv:Body>
</soapenv:Envelope>

An example XML request

POST https://api.sandbox.ebay.com/ws/api.dll HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8

X-EBAY-API-COMPATIBILITY-LEVEL : 1085
X-EBAY-API-IAF-TOKEN: v^1.1#i^1#I^3#p^3#f^...r^0#t^H4s
X-EBAY-API-SITEID : 0
X-EBAY-API-CALL-NAME : GetUser
Host: api.ebay.com
<?xml version="1.0" encoding="utf-8"?> 
<GetUserRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <Version>1085</Version>
  <MessageID>XML call: OAuth Token in trading</MessageID>
  <DetailLevel>ReturnAll</DetailLevel>
</GetUserRequest>

Note: The Platform Notification calls GetNotificationPreferences and SetNotificationPreferences work with OAuth as outlined above, however your application needs to be white listed in order to receive platform notifications. Please contact Developer Technical Support for details on getting your application white listed.

Using OAuth in Post Order API requests

The Post Order API uses the Authorization HTTP request header to pass the OAuth token with your REST request.

To make a Post Order API request using OAuth:

  1. Populate the Authorization HTTP header value with "IAF " (with a space) followed by a valid User access token.

    For example:

    Authorization : IAF v^1.1...90nH9ZfwTJRzOfW4QAAA=

Using OAuth in Business Policy Management API requests

To make a Business Policy Management API request using OAuth:

  1. Remove the HTTP header X-EBAY-SOA-SECURITY-TOKEN and its associated Auth'n'Auth token value from the request.
  2. Add the HTTP header X-EBAY-SOA-SECURITY-IAFTOKEN and populate its value with a valid User access token.

    Here's a section of the HTTP headers:

    X-EBAY-SOA-SECURITY-IAFTOKEN : v^1.1...90nH9ZfwTJRzOfW4QAAA=