Skip to main content

Here is a summary of the process that results in your application getting a token for a user:

  1. A user indicates a desire to use your application.

  2. Your application requests a session ID from eBay, and receives one.

  3. Your application constructs a URL that contains the session ID and an identifier for your application, and uses this URL to send the user to the eBay sign-in page.

  4. The user signs in to eBay.

  5. eBay serves the user the consent form for your application.

  6. The user consents.

  7. If your application hosts an AcceptURL, eBay serves the user back to that URL.

  8. Your application requests a token for the user, who is identified in the request by the session ID.

  9. eBay returns a token to your application.

Getting a token is a slightly different process for web-enabled applications (which can host AcceptURL and RejectURL) than it is for client desktop applications (which do not host URLs).

The following sections describe the processes for client/desktop applications and for web applications.

Client/Desktop Applications

Use this method of getting tokens if there is no web component to your application, or you do not wish to host an AcceptURL or RejectURL page.

In this process, some of the steps are completed by the user, some by eBay, and some by your application.

  1. A user indicates an intention to use your application (for example, by clicking a Subscribe button in your application interface).

  2. Your application makes a GetSessionID request to eBay, and receives a session ID (SessionID).

    GetSessionID is described in reference detail at GetSessionID.

    Your application uses the session ID to construct an eBay sign-in URL that sends the user to the eBay sign-in page and consent form.

  3. Use the following URL to redirect a user to the eBay sign-in page:

    https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID

    The URL must include &SessID=SessionID and &RUName=RUName. SessionID identifies the user and RUName the application. The SessionID must be URL-encoded in the sign-in URL.

    The equivalent URL for the Sandbox is:

    https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID. The user signs in on the eBay sign-in page.

  4. eBay forwards the user to your application's consent form.

  5. The user consents or rejects your application.

  6. eBay forwards the user to an eBay page that confirms their action.

  7. Your application calls FetchToken to retrieve the user token.

See Getting a Token via FetchToken.

Option 1: User Sign-in Flow Ends on eBay; Client/Desktop Application Uses FetchToken to Retrieve Token

Web/Server Applications

Use this method for getting tokens if your application has a web component and can respond to being redirected to the URLs specified in your developer account.

In this process, some of the steps are completed by the user, some by eBay, and some by your application.

  1. A user indicates an intention to use your application (for example, by clicking a Subscribe button in your application interface).

  2. Your application makes a GetSessionID request to eBay.

    GetSessionID is described in reference detail at GetSessionID.

  3. Your application receives session ID (SessionID).

  4. Your application constructs an eBay sign-in URL that sends the user to the eBay sign-in page and consent form.

    Sign-in URL for production tokens:

    https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID

    Sign-in URL for Sandbox:

    https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID

    In the URL, SessionID identifies the user and RUName the application. SessionID must be URL-encoded in the sign-in URL. It is the session ID that was obtained by calling GetSessionID.

    Note that in a web application, you can construct an eBay sign-in URL using an HTML form that contains a Submit button. For example:

    <INPUT TYPE=\"submit\" NAME=AUTHORIZE VALUE=\"Launch Auth & Auth\"
  onclick=\"window.open('https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=$RUName&amp;SessID=$SessionID');\">\n

    Your application can use an additional parameter in the sign-in URL, ruparams, to hold user data that you want passed back to your application after the user consents. After user consent, eBay adds the ruparams information to the URL that directs the user back to your AcceptURL or RejectURL page. This data is not used in any way by eBay.

    The data you pass in ruparams may consist of zero or more pieces of information, each in a variable name and URL-encoded value format. When eBay redirects to your application's AcceptURL or RejectURL, the value of ruparams is URL decoded into name-value pairs. For example, if the application sends this:

    ...&ruparams=VarA%3DB12309%26VarB%3DABC123

    eBay returns this in the URL:

    ...&VarA=B12309&VarB=ABC123

  5. The user signs in on the eBay sign-in page.

  6. eBay forwards the user to your application's consent form.

  7. In the consent form, the user consents or rejects your application.

  8. eBay redirects consenting users back to the application's AcceptURL, and rejecting users to the application's Reject URL.

  9. If you have passed user data in ruparams in the sign-in URL, eBay appends this data to the AcceptURL or RejectURL.

    Your application should present rejecting users with a meaningful error or message indicating that the application will be unable to make API calls in the user's name (that is, the user cannot use your application).

  10. The application calls FetchToken to retrieve the user token.

See Getting a Token via FetchToken.

With one-time setup complete, your application can respond to prospective users and get tokens for them.

If the application only has one user, the same process outlined in the Getting access tokens through the Developer Portal can also be used for Auth'n'Auth user tokens. The process for getting user tokens for both OAuth and Auth'n'Auth are basically the same, except that the Auth'n'Auth radio button will be selected in the User Tokens page.

Sign-in Web Application Flow Returns User to Web Application; Application Uses FetchToken to Retrieve Token

Getting a Token via FetchToken

Once the processes described in Client/Desktop Applications or Web/Server Applications have been completed, from your desktop or web application use FetchToken to retrieve tokens for its users.

When a user hits the eBay sign-in URL your application constructed during the consent process, eBay generates a user token and stores it with a user's session ID for 48 hours.

If this is your application's first time using this process to obtain a token for a user, your application should wait 5-10 seconds before calling FetchToken.

This section contains examples of using FetchToken.

FetchToken is described in reference detail in FetchToken.

The SOAP API example below shows a FetchToken call with the requester credentials in the SOAP header:

Fetching a Token Programmatically with SOAP
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xs="https://www.w3.org/2001/XMLSchema"
xmlns:ebl="urn:ebay:apis:eBLBaseComponents">
  <soap:Header>
    <ebl:RequesterCredentials soapenv:mustUnderstand="0">
	 <Credentials>
	   <AppId>MyAppID</AppId>
	   <DevId>MyDevID</DevId>
	   <AuthCert>MyCertID</AuthCert>
	 </Credentials>
    </ebl:RequesterCredentials>
  </soap:Header>
  <FetchTokenRequest xmlns="urn:ebay:apis:eBLBaseComponents">
	<SessionID>MySessionID</SessionID>
	<Version>1169</Version>
  </FetchTokenRequest>
</soap:Envelope>

Instead of passing in application keyset values into the Credentials container in the request payload, you can also pass the application keyset values in through HTTP headers. The XML API example below shows the FetchToken call with the requester credentials in the HTTP header:

X-EBAY-API-APP-NAME:MyAppID
X-EBAY-API-DEV-NAME:MyDevID
X-EBAY-API-CERT-NAME:MyCertID
X-EBAY-API-CALL-NAME:FetchToken
X-EBAY-API-SITEID:0
Content-Type:text/xml
Request Payload:
<?xml version="1.0" encoding="utf-8"?>
<FetchTokenRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <Version>1169</Version>
   <SessionID>MySessionID</SessionID>
</FetchTokenRequest>

Using Tokens

To authenticate the requester for a SOAP API call using a user token, pass the token in the header for the request. The SOAP API example below shows the header element that contains the token in bold.

Token in a SOAP Request
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xs="https://www.w3.org/2001/XMLSchema"
               xmlns:ebl="urn:ebay:apis:eBLBaseComponents">
  <soap:Header>
    <ebl:RequesterCredentials soapenv:mustUnderstand="0">
      ...
      <eBayAuthToken>
        ... USER TOKEN GOES HERE ...
      </eBayAuthToken>
    </ebl:RequesterCredentials>
  <Version>1169</Version>
  </soap:Header>
... Call body ...
</soap:Envelope>

To authenticate the requester for an XML API call using the user token, pass the token in the eBayAuthToken element in the request XML. The XML API example below shows the full XML for the GeteBayOfficialTime call.

Token in an XML Request
<?xml version="1.0" encoding="utf-8"?>
<GeteBayOfficialTimeRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken> Token goes here </eBayAuthToken>
  </RequesterCredentials>
</GeteBayOfficialTimeRequest>