This topic discusses the details and best practices for working with the eBay OAuth implementation.

Security and OAuth tokens

Access tokens are short lived—they expire quickly for security reasons—while refresh tokens are valid for an extended period of time. Refresh tokens are limited in functionality, however, and you can only use them to get a new access token (you cannot use refresh tokens to authorize requests).

Even though you cannot make a call with a refresh token, you must still consider them as sensitive and you must store them in a secure location. Like an access token or client secret, if the value of a refresh token is considered compromised, you should take immediate action to limit any possible repercussions that could stem from its misuse.

Important! OAuth tokens and credentials MUST be treated as confidential and must not be shared or exposed publicly. For the best performance and security, applications should store access tokens in memory and re-use them until they expire.

Testing with the Sandbox

The tokens you mint with the OAuth token requests work only in the environment for which the token was minted. There are three token requests for User access tokens, and you must be sure to align the target environment for each request.

When you test with User access tokens, you need to get "consent" from your Sandbox test user accounts. However, once you've finished testing, get Production access tokens by redoing the access-token flow using your Production OAuth credentials and the Production URLs. To do so, start the process afresh from the consent request step, as outlined in the topic Getting the third-party consent. The difference here is that you will be getting consent from the real users of your app, and not your Sandbox test accounts.

OAuth token best practices

The following list presents some best practices for working with access tokens and their rate limits:

  • Access tokens are short-lived in that they expire relatively quickly after they have been minted. This is a security measure meant to keep ill-intended users from abusing access tokens. Use an access token until it expires, then create a new one using either a client credentials grant for Application access tokens or a refresh token grant for User access tokens.
  • Refresh tokens are long-lived, but they can be unexpectedly revoked. For example, the associated user can change their eBay user name or they can revoke their consent. In addition, eBay can revoke a token for various reasons. With these scenarios in play, your application needs to gracefully handle User access token revocations.
  • Refresh tokens are valid for an extended period of time. When a refresh token expires, you must issue another permissions grant request to mint a new User access token for the respective user.
  • Even while access tokens are short lived, eBay strictly enforces a daily rate limit on the number of tokens you can mint with each type of grant request. Make sure your application stays within the request limits for your OAuth tokens.
  • Create your User access tokens using all the scopes needed for the current capabilities in your application, plus any capabilities you plan to add to the application. Adding a new scope to an existing User access token requires a new permission grant from each of your users, and they might balk at multiple consent requests.
  • Create tokens using only the scopes your application needs. For example, there is no need to specify a read-only scope if the corresponding view and manage scope is also being specified.
  • Store your OAuth credentials and refresh tokens on a secure server to prevent them from being hacked and used by bad actors for corrupt or possibly unlawful behavior.