Exchanging the authorization code for a User access token

When a user grants your application the authorization to take action on their behalf, eBay returns an authorization code that contains the user's consent for the specified scopes. Use the authorization code in a POST request that's commonly known as an authorization code grant request. This request gets a User access token and its associated refresh token.

The authorization code is a maximum of 1024 characters in length. Do not store this value, instead use the value only as a run-time parameter that's passed directly to the authorization code grant.

Configuring the request

You need to configure three parts of a client credentials grant request:

The target endpoint
The HTTP request headers
The request payload

Setting the target endpoint

The endpoint you use depends on the environment you're targeting:

OAuth token-request endpoints
Environment	Endpoint (HTTP method + URL)
Sandbox	`POST https://api.sandbox.ebay.com/identity/v1/oauth2/token`
Production	`POST https://api.ebay.com/identity/v1/oauth2/token`

Configuring the HTTP request headers

Set the following HTTP request headers:

Content-Type – Must be set to: application/x-www-form-urlencoded
Authorization – The word Basic followed by your Base64-encoded OAuth credentials (<client_id>:<client_secret>)

For details, see Generating your Base64-encoded credentials.

Configuring the request payload

Format the payload of your POST request with the following values:

Set grant_type to authorization_code.
Set redirect_uri to the RuName value assigned to your application and the environment you're targeting.

For details, see Getting your redirect_uri value.
Set code to the URL-encoded authorization code value returned to you by eBay when the user granted their consent.

For details, see Getting the third-party's consent.

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

The authorization code grant request

The authorization code grant is a request that mints a new User access token. Use the token to make requests to API methods that match the scopes configured into the access token.

Configure your request using the following call specifics:

  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:
    grant_type=authorization_code
    code=<authorization-code-value>
    redirect_uri=<RuName-value>

Example cURL request

The following command shows how to configure the authorization code grant request with cURL (wrapped for readability):

curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic RGF2eURldmUtRG2 ... ZTVjLTIxMjg=' \
  -d 'grant_type=authorization_code&
      code=v%5E1.1%23i%5E1%23f% ... 3D%3D&
      redirect_uri=Davy_Developer-DavyDeve-DavysT-euiukxwt'

Response containing the User access token

When you issue the authorization code grant request, eBay returns a JSON object containing the fields shown here:

  {
    "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"
  }

Use the access token to authorize your API requests.

Because this example targets the Sandbox environment, this access token can be used to make API calls to only the Sandbox. To make requests to the Production environment, repeat the token-generating process using the Production environment values (the OAuth credentials, RuName, and URLs) in each of the token requests you sent to eBay.

About the User access token

The expires_in value returned with the newly-minted User access token indicates the number of seconds that token is valid.

In the example above, the token remains valid for 7,200 seconds (2 hours) from the time it was generated. After the token expires, you will need to renew it using the supplied refresh token.

The refresh token

While User access tokens are short-lived, the associated refresh_token is a long-lived value that you can use to update an expired User access token. This means you do not have to get the user's consent each time you need a new User access token.

To update the access token after it expires, see Using a refresh token to update a User access token.