Trading API

XML Flow Tutorial: Getting Tokens

This tutorial demonstrates how an application gets a token for a user.

The first step is the preparatory setup that enables an application to receive user tokens. This setup is done on the eBay Developers Program site (developer.ebay.com).

The second step involves interactions between an application and a user:

The application makes several API calls to eBay during the process of getting a token. When a step includes an API call, it provides a link to XML call samples in the Trading API Reference. The samples show how to perform those steps using the API.

What this Tutorial Covers

This tutorial contains the following sections:

Back to top

Complete Source Code

The API Flow tutorials use raw XML requests and responses. The XML call samples described in this tutorial can all be found in the Trading API Reference.

Before You Begin

All the calls in the tutorial are performed in the Sandbox environment, using a test user and the API Test Tool. If you want to perform the steps in this tutorial for your own application in the Sandbox, you'll need to do the following:

Requirements for this tutorial

The tutorial has no specific code requirements. After you log in, you can run the XML samples in the API Test Tool on the eBay Developers Program website.

Back to top

Step 1: Setting Up an Application to Receive Tokens

The following is for Web/Server based applications. For information about Client/Desktop applications, see Client/Desktop Applications.

Typically, an application needs to be set up to receive tokens only once.

This section shows how the developer of MagicLister uses the screens in the My Account page, to:

  1. The developer signs in to developer.ebay.com and goes to his My Account page.

  2. He selects the application settings tab, where he does the following:
    • Selects an environment
      Use the Sandbox environment for testing, and the Production environment to set up your application for eBay users. In this example, we used Sandbox.
    • Selects the keyset to use for the MagicLister application.

  3. Under Customize the eBay User Consent Form, he clicks the Customize the eBay User Consent Form link to configure the application level settings that customize the user consent flow.

    • Show Application Detail: Determines if your application's consent form displays your logo, URL, and description.

    • Application URL: Specifies the URL you want to have displayed in the consent form, usually an information page about your application.

    • Application Logo: The URL for your logo.

      Acceptable formats for application logos include JPG, GIF, PNG, BMP, and TIF image files. JPG is recommended. If you use PNG, it will be converted to JPG (or GIF) format. The maximum file size is 7MB. eBay Picture Services (EPS) downscales and compresses the picture to store it at the different sizes in the imageset. For best results, upload a picture that has a minimum of 1000 pixels on the longer side.

    In this example, he opts to show application details, and supplies the MagicLister URL and the MagicLister logo.

  4. Under Manage Your RuNames, he clicks Generate Runame. After a minute or so, the page refreshes with a success message and a new Runame. An RuName contains settings that govern:

    • The content that users will see on the consent form
    • Rules about how the application authenticates users and gets tokens
    • Application URLs such as the AcceptURL that eBay uses to return consenting users to the application
  5. Under Manage Your RuNames, he clicks Show Details for the new RuName. This opens the form where he sets up application consent details:

    • Display Title: The company or application name to be displayed on the consent form.

    • Display Description: A description of your application that will be displayed on the consent form.

    • Token Return Method: Select "FetchToken," and your application will use the FetchToken to retrieve the token once the user has consented. "FetchToken" is the recommended method.

    • Authorization Type:
      • Authorization - Use this if your application needs to access eBay users' data via eBay APIs.
      • IDVerification - Use this if your application needs only to confirm users' eBay UserIDs, and does not need to access users' private data. Users will be presented with a more casual text on the consent form, and a token is not generated for the application. Note: The application needs to use the ConfirmIdentity API call to complete the final UserID confirmation step. Because there is no token, there is no need to call FetchToken.

    • Application Type: Specify whether your application is web-based and has a URL to which you would like your users returned after they consent, or is a desktop application without a URL.

    • Accept Redirect URL: The URL to which users will be directed after they consent to the web application authenticating them. This URL must support SSL and must use the HTTPS protocol.

      If your application is capable of serving web pages, you should provide your own web page and set this URL. If your application cannot serve web pages, this URL defaults to a standard eBay accept-response page (the eBay page and URL are subject to change by eBay).

    • Reject Redirect URL: The URL to which users are directed when they do not consent.

      If your application is capable of serving web pages, you should provide your own web page and set this URL. If your application cannot serve web pages, this URL defaults to a standard eBay accept-response page (the eBay page and URL are subject to change by eBay).

    • PrivacyPolicyURL: The URL at which your application's privacy policy can be read.

    For more information see, Getting Tokens.

  6. After making changes, click Save Settings.

The MagicLister application is now set up to start getting tokens.

Back to top

Step 2: Getting a Token for a User

This section shows:

  1. Magical Bookseller goes to the MagicLister site, where she clicks a Subscribe button or otherwise lets the application know that she intends to use it.

  2. MagicLister sends a GetSessionID call to eBay, with the MagicLister RuName. This call will retrieve a SessionID that will identify Magical Bookseller after she signs in to eBay.

    For an example of the GetSessionID request and response, see http://developer.ebay.com/DevZone/XML/docs/Reference/eBay/GetSessionID.html#Samples .

  3. MagicLister URL-encodes the SessionID and then constructs a URL containing the SessionID and the RuName, and uses this URL to send Magical Bookseller to the eBay Sandbox sign-in page. In this scenario, the GetSessionID call was made using the API Test Tool, and the SessionID was pasted into a URL along with MagicLister's RuName, in a browser window.

    The URL takes this form:

  4. https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RuName=YourRuNameHere&SessID=YourSessionIDHere
  5. Magical Bookseller signs in to eBay.

  6. eBay sends Magical Bookseller to the user consent form that MagicLister configured in the application settings tab, in the first section of this scenario.

  7. When Magical Bookseller clicks "I agree," eBay sends her to MagicLister's AcceptURL.

  8. When Magical Bookseller arrives at its AcceptURL, MagicLister sends a FetchToken request to eBay with the SessionID.

    FetchToken: retrieves the token.

    Notice that MagicLister includes its credentials with this FetchToken call--the developer ID, the application ID, and the AuthCert. That's because this is one of the few authenticated user-related calls that you make when you don't already have a token. If you're using SOAP, the credentials need to be in the SOAP header; for XML you include them in the RequesterCredentials field in the request body.

  9. FetchToken returns a user token for Magical Bookseller to MagicLister.

    MagicLister saves the token and the token expiration date from the FetchToken response.

  10. MagicLister tests the token by making a GeteBayOfficialTime request using the new token.

Back to top

Notes and Next Steps

This section contains notes about the tutorial and suggestions for extending it.

What's Next

Here are some suggestions for ways you could modify or extend the tutorial to learn more about the API:

Additional Resources

eBay Knowledge Base includes applications that incorporate the process of getting user tokens. The applications are here:

More information about the Trading API is available at these locations:

User-Contributed Notes

 

Copyright © 2009–2014 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.