Authorization code for web applications

The Authorization Code grant type is the most common way for API clients to acquire access tokens that can be used to act on behalf of a marketplace user.  When used by web server applications, the client secret is required when requesting the access token pin.  Given this, the developer is responsible for securing the secret in their system.  

In the Authorization Code flow, API clients authenticate an end user and obtain an authorization code (a one-time use token). The code is then exchanged for an access token, and optionally a refresh token.

The following diagram illustrates this flow:

1. The application initiates authorization by sending a request to the marketplace's authorization endpoint.

   Sample request:

   https://marketplace.example.com/oauth2/authorize?response_type=code&client_id=appdirect-49&scope=ROLE_USER%20ROLE_BILLING_ADMIN&state=bf0jksdldqj&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth2%2Freturn

   Parameter	Description
   response_type	Must be code, which indicates that this is the Authorization Code grant type.
   client_id	Your API client ID.
   scope	A space-separated list of requested scopes.
   redirect_uri	Endpoint where the marketplace will redirect the user to with the authorization code. It must match the return URL registered with your API client.
   state (optional)	An opaque value used by your application to maintain state. The marketplace includes this value when redirecting to the redirect_uri. See the OAuth 2.0 specification for details on how to use this to prevent cross-site request forgery.

2. The user is authenticated with the marketplace.

3. An authorization code is returned to the redirect_uri passed in step 1.

   note

   This URI must also be registered within the product configuration.

   The state parameter is also returned untouched.

   Sample request:

   https://www.example.com/oauth2/return?code=Ib08m7&state=bf0jksdldqj

4. The application sends a POST request to the token endpoint to exchange the code for an access token and optionally the refresh token. This request must be authenticated (basic authentication) using the client ID and secret.

   Sample request:

   curl -X POST -u appdirect-49:9vY0s4yb2pbnP7Vz "https://marketplace.example.com/oauth2/token?grant_type=authorization_code&code=Ib08m7&redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth2%2Freturn"

   Parameter	Description
   grant_type	Must be authorization_code, indicating that this is the Authorization Code grant type.
   code	The authorization code returned to your API client. A space-separated list of requested scopes.
   redirect_uri	The return URL registered with your API client. It must match the redirect_uri used in the authorization code request. Endpoint where the marketplace will redirect the user to with the authorization code. Must match the return URL registered with your API client.

5. The access token and, optionally, the refresh token are returned.   ​

   Sample response:

   {
       "access_token": "7iVGxe84f1ew6QENpCD3",
       "refresh_token": "qsdfbasfsa1bjbfdjbfs",
       "token_type": "bearer",
       "expires_in": 43199,
       "scope": "ROLE_USER ROLE_BILLING_ADMIN"
   }

6. Call an AppDirect API and include the access token in the Authorization header as a bearer token.

   Sample request:

       curl -H 'Authorization: Bearer 7iVGxe84f1ew6QENpCD3' "http://marketplace.example.com/api/account/v2/subscriptions/6c31d072-8480-11e3-b2f4-22000ae812a4/assignments"

7. Receive the API response.