Skip to main content

There are two application use cases, or models. The models differ only by the number of users supported by the application.

In the Single User Model, the application supports only a single user. In this model, you need only one Auth'n'Auth token. You can generate a single token for your application's user with the User Tokens (eBay Sign-In) page in your developer account. An Auth'n'Auth token created in the Production environment is associated with an eBay user ID, and an auth'n'auth token created in the Sandbox environment is associated with a Sandbox test user.

In the Solutions Provider Model, the application supports multiple users. For this you would want to implement the ability to get user tokens directly from within your application. The following sections describe how to configure your application to get tokens for eBay users, how to get tokens that will enable users to make use of your application, how to use tokens, and how to replace them when they expire.

The following tutorial walks you through setting up your application to receive tokens and receiving a token for a user.

Life Span and Uniqueness

Typically, an application obtains a user token for each user via the user sign-in and consent process and stores the token for subsequent use. If you will be storing user tokens in a database, here's what you need to know.

  • It can be up to 2KB in length and is base 64 encoded

  • It can contain: a to z, A to Z, 0 to 9, asterisk, slash, plus ( * / +)

Tokens are valid for 18 months across multiple sessions of the application. Seven (7) days before a token is due to expire, eBay returns the expiration date in the HardExpirationWarning Element field in the response of all calls the application makes on behalf of that eBay user. When your application detects this field, it must redirect the user to the sign-in page on the eBay site by the date in this warning, or the token ceases to work as a means to authenticate that eBay user.

Applications are notified at least seven days before the expiration of a token at the end of its lifetime, so that they can initiate the process of generating a new token for the user. A new token is usually generated before the old one actually expires. But note, the creation of a new token for a given application/user combination invalidates the prior token.

eBay recommends messaging end users several months before the token expiration date to ensure the user has plenty of time to reauthorize your application. Keep track of the date on which you created the token, and assume that it should be valid for 18 months unless otherwise indicated by eBay.

If a token expires and no new token is generated, the application will be unable to make API calls in that user's name. This has no effect on the user's eBay account or any other application that they use. Once a new token has been generated, the application will again be able to make function calls on that user's behalf. See Revoked tokens for a list of what can cause a token to expire.

Once a token has expired, all calls using that token will fail with error 932: "Auth token is hard expired." To avoid unexpected user token failures, your application should include logic to handle this error.

HardExpirationWarning Element

In SOAP-formatted calls, the seven-day warning is returned in the HardExpirationWarning element. The element is returned in the header of the response to an API call made within the 7-day warning period.

<?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">
      <HardExpirationWarning>
      ... DATE OF EXPIRATION HERE ...
      </HardExpirationWarning>
    </ebl:RequesterCredentials>
  </soap:Header>
... Call body ...
</soap:Envelope>
XML Seven-Day Warning Response
<?xml version="1.0" encoding="UTF-8"?>
  <GeteBayOfficialTimeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2005-01-12T18:29:48.312Z</Timestamp>
  <Ack>Success</Ack>
  <CorrelationID>00000000-00000000-00000000-00000000-00000000-00000000-0000000000
  </CorrelationID>
  <Version>393</Version>
  <Build>20050110220901</Build>
  <HardExpirationWarning>2005-01-14 03:34:00</HardExpirationWarning>
</GeteBayOfficialTimeResponse>

Revoked tokens

EBay users can revoke tokens by going to the Third-party app access page in My eBay.

When a user revokes a token for an application, that token expires immediately. Any API calls made with the expired token fail with an error (error code 16110). eBay revokes a token due to security concerns

If eBay detects suspicious activity that indicates a possible security compromise of an account or application, all affected user tokens are revoked immediately. Any API calls made with the revoked token fail (error code 17470).