Getting Tokens for Applications with Multiple Users

This chapter discusses getting tokens for Client/Desktop and Web/Server applications.

Subtopics

Summary of the Process

Option 1: Client/Desktop Applications

Option 2: Web/Server Applications

Getting a Token via FetchToken

Summary of the Process

Here is a summary of the process that results in your web 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.

Option 1: 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).
  3. GetSessionID is described in reference detail at GetSessionID.

  4. 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.
  5. 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

  6. The user signs in on the eBay sign-in page.
  7. eBay forwards the user to your application's consent form.
  8. The user consents or rejects your application.
  9. eBay forwards the user to an eBay page that confirms their action (they are thanked and told, "You may close this window").
  10. Your application calls FetchToken to retrieve the user token
  11. See Getting a Token via FetchToken.

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

Option 2: 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 on your MyAccount 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.
  3. GetSessionID is described in reference detail at GetSessionID.

  4. Your application receives session ID (SessionID).
  5. Your application constructs an eBay sign-in URL that sends the user to the eBay sign-in page and consent form.
  6. 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&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

  7. The user signs in on the eBay sign-in page.
  8. eBay forwards the user to your application's consent form.
  9. In the consent form, the user consents or rejects your application.
  10. eBay redirects consenting users back to the application's AcceptURL, and rejecting users to the application's Reject URL.
  11. 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 calls to API calls in the user's name (that is, the user cannot use your application).

  12. The application then calls FetchToken to retrieve the user token.
  13. See Getting a Token via FetchToken.

    With one-time setup complete (see XML Flow Tutorial: Getting Tokens), your application can respond to prospective users and get tokens for them.

    If there is only one user of the application, a much simpler method is available for getting tokens. See Token Tool.

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

Getting a Token via FetchToken

Once the processes described in Option 1: Client/Desktop Applications or Option 2: 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>

The XML API example below shows the FetchToken call with the requester credentials in the HTTP header:

Fetching a Token Programmatically with XML

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>

For an explanation of how to use tokens, see Using Tokens.