http://developer.ebay.com/DevZone/XML/docs/WebHelp/GettingTokens-Getting_Tokens_for_Applications_with_Multiple_Users.html
Getting Started > Getting Tokens > Getting Tokens for Applications with Multiple Users 
 



Getting Tokens for Applications with Multiple Users

With one-time setup complete (see Configuring the Consent Flow for Applications with Multiple Users), an application can redirect users to the sign-in page on the eBay site to initiate the user token generation process.

Note: An alternate means of obtaining a token is available if there is only one user of the application. See Token Tool.

In this section:

Option 1: Client/Desktop Applications

Option 2: Web/Server Applications

Preparing the URL for User Sign-in

The Form of the Accept Redirect URL

Getting a Token via FetchToken

Getting a token is a slightly different process for web/server applications (that can serve URLs to users) than it is for client desktop applications (which do not provide URLs). The process for both types of applications share the following steps:

  1. Get a session ID for a user. The application calls GetSessionID to retrieve a session ID, which identifies the user and your application to eBay, allowing them access to the consent form. Note that the session ID is valid for only five minutes after it is retrieved.
  2. Send the user to the consent form. The application constructs a URL for the eBay sign-in page that includes parameters for SessID (a parameter that contains the session ID, and is expected in the sign-in URL) and RuName, and sends the user to the eBay sign-in page. eBay then redirects the user to the Accept Redirect URL or Reject Redirect URL, if you supplied these URLs as described in Generate an RuName for Your Application, or to the eBay "Thank You" page if you did not supply the URLs.
  3. Retrieve the user token. Your application calls FetchToken and includes the SessionID, and eBay returns the user token. See Getting a Token via FetchToken. Once you get a token, you can persist it in a secure database. FetchToken need only be called once per user (and when the token expires again in 18 months).

The following sections illustrate the processes for desktop and web applications.

Option 1: Client/Desktop Applications

If there is no web component to your application, or you do not wish to host an AcceptURL or RejectURL page, this is the only option for your application to obtain a user token. In this option:

  1. The application calls GetSessionID and gets a session ID (SessionID).
  2. The application constructs an eBay sign-in URL that contains the SessionID and sends the user to the sign-in and consent page. Here, the user consents to the creation of a user token for the application. See Preparing the URL for User Sign-in.
  3. The user is forwarded to an eBay page that confirms their action (they are thanked and told, "You may close this window").
  4. The calling application then calls FetchToken to retrieve the user token, using the same session ID that was sent in the sign-in URL. See Getting a Token via FetchToken.
    5. Figure 6-1 Option 1: User Sign-in Flow Ends on eBay; Client/Desktop Application Uses FetchToken to Retrieve Token

Option 2: Web/Server Applications

Most applications have a web component and can respond to being redirected to the URLs specified on your MyAccount page. The option discussed in this section is suited for applications that can handle a redirect from eBay. In this option:

  1. The user initiates the consent flow and the application calls GetSessionID.
  2. The application constructs an eBay sign-in URL that contains a SessionID parameter and sends the user to the sign-in and consent page. Here, the user consents to the creation of a user token for the application. See Preparing the URL for User Sign-in.

    3. In a web application, this is typically done with a 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"

    Here, $RuName is your application's RuName and $SessionID is the session ID that was obtained by calling GetSessionID and storing the SessionID value in a session variable.

  3. eBay redirects the user back to the application's AcceptURL or RejectURL page. See The Form of the Accept Redirect URL for more information.
  4. The calling application then calls FetchToken to retrieve the user token, using the same session ID that was sent in the sign-in URL. eBay appends information to this URL, along with the user token and other various information (such as values pertaining to the hard expiration date of that token and any information that the application sent along for the round-trip ride) via ruparams. See Getting a Token via FetchToken.
    5. Figure 6-2 Option 2: Sign-in Flow Returns User to Web Application; Application Uses FetchToken to Retrieve Token

Preparing the URL for User Sign-in

To generate a user token, an application must 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 can include &ruparams=ruparams.

The resulting web page looks very similar to the standard eBay sign-in page. It also includes the name of the application and some special token-related text.

The equivalent URL for the Sandbox is:

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

Note: Applications are not allowed to frame the eBay sign-in page. The redirect to the sign-in page must be performed without the use of frames.

The Form of the Accept Redirect URL

Assuming that the user successfully signs in at the eBay sign-in page and accepts the application representation terms, eBay redirects the user to the application's Accept URL. This URL is supplied by the application's proprietors when registering the application and is maintained on file at eBay for the purpose of this redirection during the token generation process. By default, the application can retrieve the token for the user from the Accept URL, although the application can specify in the application authentication data entry that it will be retrieving the token programmatically instead.

In cases where the user does not accept the consent form, eBay redirects to the application's Reject URL. In doing so, eBay appends to the Reject URL the ruparams. This passes back to the application the identifier the application uses to associate the failed user authentication with the appropriate application user. The application should present the user with a meaningful error or message indicating the failure and that the application will be unable to make calls to API calls in the user's name (that is, the user essentially cannot use the application).

Getting a Token via FetchToken

Any application can use FetchToken to retrieve a user's token. For applications that are not Web-based (or for which a redirection to AcceptURL is not fitting), this is the only way to obtain a user's token. FetchToken is described in detail in FetchToken.

When directing the user to the eBay sign-in page for new token creation, the application adds the session ID, a parameter whose value is generated uniquely for the user's session by eBay and retrieved by the application using GetSessionID. GetSessionID is described in detail at GetSessionID.

The presence of the session ID triggers eBay to generate a user token and to store it with the session ID. eBay stores this pair for 48 hours, enabling the application to retrieve the user token via FetchToken within a reasonable time after directing the user to the sign-in and consent pages. If this is the application's first time using this process to obtain a token for the user, the application should wait 5-10 seconds before calling FetchToken. Otherwise, the application can use FetchToken to retrieve the token immediately.

The following example shows a custom RuName value and a SessionID value.

https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RuName=CodeMunger-BR549-BidList&SessID=DkQAAA**5d28f02a1180a11448559fa5ffffffd5

The equivalent URL for the Sandbox environment is:

https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RuName=CodeMunger-BR549-BidList&SessID=DkQAAA**5d28f02a1180a11448559fa5ffffffd5

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

Example 6-1 Fetching a Token Programmatically 
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xs="http://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>613</Version> 
  </FetchTokenRequest> 
</soap:Envelope>

The XML API example below shows how to use the FetchToken call:

Example 6-2 Fetching a Token Programmatically 
<?xml version="1.0" encoding="utf-8"?> 
<FetchTokenRequest xmlns="urn:ebay:apis:eBLBaseComponents"> 
  <Version>613</Version> 
   <RequesterCredentials> 
     <DevId>MyDevID</DevId> 
     <AppId>MyAppID</AppId> 
     <AuthCert>MyAuthCert</AuthCert> 
   </RequesterCredentials> 
   <SessionID>MySessionID</SessionID> 
</FetchTokenRequest>




User-Contributed Notes

   
 
 
 



 
Getting Started > Getting Tokens > Getting Tokens for Applications with Multiple Users 
http://developer.ebay.com/DevZone/XML/docs/WebHelp/GettingTokens-Getting_Tokens_for_Applications_with_Multiple_Users.html
© 2004–2010 eBay Inc. All rights reserved. Version 655