Quick reference — OAuth authorization code grant

This Quick Reference assumes you're familiar with the concepts covered in the topic The authorization code grant flow.

The authorization code grant request generates a User access token. You need the following values to complete the process:

  • Your application's OAuth credentials for the environment you're targeting.

    For details, see Getting your OAuth credentials.

  • Your application's RuName for the environment you're targeting.

    For details, see Getting your RuName value.

  • A list of OAuth scopes that provide access to the interfaces you call.

    For details, see Specifying OAuth scopes.

  • A state value.

    An opaque value used by the client to maintain state between the request and callback.

    The authorization server returns the same value supplied in the request when it redirects the user-agent back to the client's accept URL. While the state value is optional, we recommend you supply this value and use it to prevent cross-site request forgery, as described in Section 10.12 of the OAuth spec.

Getting an authorization code

The user grant redirect requires following values:

  • The client ID OAuth credential
  • The RuName value that eBay assigns to your application
  • The OAuth scope(s) required for access to the REST interfaces you plan to call
  • A state value (optional)
Redirect URL to get a user's authorization code
  /* URL redirects a user to the apps Grant Application Access page (wrapped for readability) */

  https://signin.sandbox.ebay.com/authorize?
    client_id=<your-client-id-value>&
    redirect_uri=<your-RuName-value>&
    response_type=code&
    state=<client-supplied-state-value>&
    scope=https://api.ebay.com/oauth/api_scope/sell.account%20 /
          https://api.ebay.com/oauth/api_scope/sell.inventory

When you issue the following redirect, the user is directed to your application's Grant Application Access page, a custom page for your app that is compiled and hosted by eBay.

Getting a User access token using the auth code

The authorization code grant request requires the following values:

  • The Base64-encoded OAuth credentials
  • The authorization code value returned from the user grant
  • The RuName value that eBay assigns to your application

Tip: The authorization code returned by eBay is URL-encoded. This value must be URL-encoded when you use it to get your access token by passing the value in the code parameter of the token-request call. However, if the method you use to get the access token URL-encodes the values you pass, then you must URL-decode the authorization code before using it to get your access token.

Request to get a User access token
  HTTP method:   POST
  URL (Sandbox): https://api.sandbox.ebay.com/identity/v1/oauth2/token

  HTTP headers:
    Content-Type = application/x-www-form-urlencoded
    Authorization = Basic <B64-encoded-oauth-credentials>

  Request body (wrapped for readability):
    grant_type=authorization_code&
    code=<authorization-code-value>&
    redirect_uri=<RuName-value>
Response with a User token
    {
    "access_token": "v^1.1#i^1#p^3#r^1...XzMjRV4xMjg0",
    "expires_in": 7200,
    "refresh_token": "v^1.1#i^1#p^3#r^1...zYjRV4xMjg0",
    "refresh_token_expires_in": 47304000,
    "token_type": "User Access Token"
  }

Using a refresh token to update a User access token

The refresh token grant request requires the following values:

  • The Base64-encoded OAuth credentials
  • The user's refresh token value
  • The OAuth scope(s) required for access to the REST interfaces you plan to call
Call to refresh a User access token using a refresh token
  HTTP method:   POST
  URL (Sandbox): https://api.sandbox.ebay.com/identity/v1/oauth2/token

  HTTP headers:
    Content-Type = application/x-www-form-urlencoded
    Authorization = Basic <B64-encoded-oauth-credentials>

   Request body (wrapped for readability):
      grant_type=refresh_token&
      refresh_token=<your-refresh-token-value>&
      scope=https://api.ebay.com/oauth/api_scope/sell.account%20 /
            https://api.ebay.com/oauth/api_scope/sell.inventory

Tip: The scopes that you use in this refresh-token call must match the scopes that were used in the redirect call that started the process to produce the original refresh token. Remember, the user grant returns an authorization code that you use to generate the refresh token.