Using OAuth with the eBay traditional APIs

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

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 require you to 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 multiple 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
Shopping API

All of the above APIs, with the exception of the Shopping API, require user access tokens created with the The authorization code grant flow. The Shopping API requires an application token created with the The client credentials grant flow. Later in this section, the methods for passing in OAuth tokens for each of these APIs are explained.

Like Auth'n'Auth, the OAuth authorization code grant flow involves delegation via a user consent. With this, your application must redirect the user to a Grant Application 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 for the eBay user.

OAuth scopes and the traditional APIs

The traditional APIs do not use OAuth scopes.

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:

Remove the <RequesterCredentials> field and its associated value from the request payload (this field is used to pass your Auth'n'Auth credentials).
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
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
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>1209</urn:Version>
      <urn:MessageID>Soap call - OAuth Token in trading</urn:MessageID>
      <urn:DetailLevel>ReturnAll</urn:DetailLevel>
    </urn:GetUserRequest>
  </soapenv:Body>
</soapenv:Envelope>

A non-SOAP example XML request

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

X-EBAY-API-COMPATIBILITY-LEVEL : 1209
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>1209</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. See Post-Order API – Making a Call for more information about using the Authorization header.

To make a Post Order API request using OAuth:

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:

Remove the HTTP header X-EBAY-SOA-SECURITY-TOKEN and its associated Auth'n'Auth token value from the request.
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=
```

Using OAuth in Shopping API requests

For the Shopping API, simply include the X-EBAY-API-IAF-TOKEN HTTP header and pass in the OAuth application token value in that header.