The authorization code grant flow

This topic describes getting an OAuth access token using an authorization code grant.

The access token retrieved from this process is called a User access token. For details on token types and more, see Access token types.

OAuth client libraries

The processes in this topic describe how to manually get OAuth tokens. To help with this process, eBay offers two client libraries that you can use to quickly implement the minting of OAuth tokens in your applications:

Topic sections

Sequence for getting and using a User access token

The following sequence diagram outlines the authorization code grant flow, where a User access token is minted, then used in an API request:

Authorization token process flow
 Sequence diagram for generating a User access token

Getting a new User access token with the authorization code grant flow is a two-step process where you follow a consent request with an authorization code grant request. To mint a new User access token:

  1. Get the account-owner's consent with a consent request.

  2. Turn the user's consent into a User access token with an authorization code grant request.

 For details on the input values needed to make these requests, see Configuring OAuth request parameters.

Getting user consent

From the application, redirect the user to the app's Grant Application Access page with an HTML redirect that uses the following syntax (wrapped for readability):

/* URL redirects a user to the application's Grant Application Access page */

  https://auth.sandbox.ebay.com/oauth2/authorize?
    client_id=<app-client-id-value>&
    redirect_uri=<app-RuName-value>&
    response_type=code&
    state=<custom-state-value>&
    scope=<scopeList>   // a URL-encoded string of space-separated scopes

The app's HTML request redirects the user to your application's Grant Application Access page, where the user is allowed to Accept the terms of use for your app.

If the user grants consent, they are redirected back to your app. The redirect back to your app includes an authorization code, which you exchange for a User access token using the authorization code grant request.

 For complete details on getting a user's consent, see Getting user consent.

Getting a User access token

Using the authorization code returned by the consent request, mint a new User access token with an authorization code grant request.

Authorization code grant

  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

A successful authorization code grant request returns a JSON object that contains an User access token, as shown in this response:

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

To use an access token to authorize an API request, pass the token value in the Authorize HTTP header, as described in HTTP request headers.

In the above example, the expires_in element is set to 7,200 seconds, meaning this token is valid for two hours from the time it was generated. For continued access after the token expires, you must mint a new token using the associated refresh token.

 For complete details on this request, see Exchanging the authorization code for a User access token.

Updating an expired access token with a refresh token

When you mint a new User access token, the new token is returned with a refresh token. Use the refresh token to renew the User access token after the original access token expires.

 For complete details on updating expired access tokens, see Using a refresh token to update a User access token.