Authorization Code Grant

LWA for Websites

STEP 1:
Register for LWA

→

STEP 2:
Add a LWA Button to Your Website

→

STEP 3:
Add the LWA SDK for JavaScript

→

STEP 4:
Implement Authorization Code Grant

→

STEP 5:
Dynamically Redirect Users

→

STEP 6:
Obtain Customer Profile Info

→

STEP 7:
Log Out Users

→

STEP 8:
Integrate with Your Account System

An Authorization Code grant allows a client (typically a website) to direct the user-agent (a user's browser) to a URI at Amazon. The user is then presented with a page asking to grant the website permission to the user's profile. After the user approves the request, the client receives the authorization code and can trade that code for an access token and refresh token.

After the client has the access token, they can read the customer profile. For more details on the customer experience, see Authorization Grants.

If the user refuses the request, the client receives an error from the authorization service .

Authorization Request
- Option 1: Server Apps
- Option 2: Browser-Based Apps
Authorization Response
Authorization Errors
Access Token Request
Access Token Response
Access Token Errors
Using Refresh Tokens

Authorization Request

To request authorization, the client (website) must redirect the user-agent (browser) to make a secure HTTP call to https://www.amazon.com/ap/oa with the following parameters. If you are using the Authorization header to request access tokens, note that it should be a base-64 encoding of client_id:client:secret.

Parameter	Description
`client_id`	REQUIRED. The client identifier . This is provided when you register your website as a client for Login with Amazon. Maximum size of 100 bytes.
`scope`	REQUIRED. The scope of the request. Must be `profile`, `profile:user_id`, `postal_code`, or some combination, separated by spaces (e.g. `profile%20postal_code`). For more information, see Customer Profile.
`response_type`	REQUIRED. The type of response requested. Must be `code` for this scenario.
`redirect_uri`	REQUIRED. The HTTPS address where the authorization service should redirect the user.
`state`	RECOMMENDED. An opaque value used by the client to maintain state between this request and the response. The authorization service will include this value when redirecting the user back to the client. It is also used to prevent cross-site request forgery. For more information, see Cross-site Request Forgery.
`code_challenge`	RECOMMENDED. Used to secure authorization code grants via Proof Key for Code Exchange (PKCE). This must be used for Browser-Based Applications, and is recommended for all application types. For more information, see the PKCE RFC.
`code_challenge_method`	RECOMMENDED. The method used to encode the `code_verifier` for the `code_challenge` parameter. Recommended is `S256`. Can also be `plain`. Defaults to `plain` if no option is provided.

For example:

https://www.amazon.com/ap/oa?client_id=foodev
&scope=profile
&response_type=code
&state=208257577ll0975l93l2l59l895857093449424
&redirect_uri=https://client.example.com/auth_popup/token
&code_challenge=Fw7s3XHRVb2m1nT7s646UrYiYLMJ54as0ZIU_injyqw
&code_challenge_method=S256

To make an authorization request using the Login with Amazon SDK for JavaScript, you must fill out an options object and call amazon.Login.authorize.

Option 1: Server Apps

For apps that can use server-side scripting. This is the recommended integration. It is considered more secure since the token is never exposed to the user. Both refresh token and access token are returned. Refresh token can be used to obtain new access tokens without involving the user.

options = { } ;
options.scope = 'profile';
options.response_type='code';
amazon.Login.authorize(options, function(response) {
  if ( response.error ) {
   alert('oauth error ' + response.error);
   return;
  }
  <!-- Pass response.code to your server, and use it to request refresh and
  access token. -->
});

Option 2: Browser-Based Apps

Note: Browser-Based Apps are not supported by the LWA SDK for JavaScript on Internet Explorer 9 or below.

For JavaScript apps where there is no server support. PKCE must be used (options.pkce = true) since browsers cannot securely store client_secret. Since the user's browser makes the access token request, the user is exposed to the access token. From a strict security perspective, it can be preferable to conceal this information. For this reason, a refresh token is not returned. When the access token expires, the user must re-authenticate to continue accessing the resources. If your architecture supports server-side scripting, we recommend doing the code to token exchange on the server (Option 1).

options = { } ;
options.scope = 'profile';
options.pkce = true; // SDK generates a `code_verifier` and `code_challenge`
amazon.Login.authorize(options, function(response) {
  if ( response.error ) {
   alert('oauth error ' + response.error);
   return;
  }
  amazon.Login.retrieveToken(response.code, function(response) {
    if ( response.error ) {
      alert('oauth error ' + response.error);
      return;
    }
    alert('Access Token: ' + response.access_token);
  });
});

The first parameter to amazon.Login.authorize is always the options object. The second parameter is either a JavaScript function to handle the authorization response, or a redirect URI to another page. The URI must belong to the same domain as the page calling the SDK, and it must be specified using HTTPS.

For example:

options = {} ;
options.scope = 'profile';
options.response_type = 'code';
amazon.Login.authorize(options, 'https://mysite.com/redirect_here');

Tip: If you would like to use the Login with Amazon SDK for JavaScript to request an Authorization Code grant, you must first have your page load the Login with Amazon SDK for JavaScript. See Installing the JavaScript SDK.

After the user has either approved or denied the request, the authorization server will redirect the user to a redirect_uri. The client will then receive an Authorization Response (described below).

Authorization Response

After the client (website) directs the user-agent (browser) to make an Authorization Request, the authorization service will redirect the user-agent to a URI specified by the client. If the user granted the request for access, that URI will contain a code parameter containing the authorization code and scope parameter containing a + separated list of scopes the user consented to. For example:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBezQQYbYS6WxSbIA
&state=208257577ll0975l93l2l59l895857093449424
&scope=profile

The authorization code can range from 18 to 128 characters. An authorization code is valid for 5 minutes.

The redirect also copies the state passed by the user-agent in the authorization request. This value allows you to keep track of the user's state before the request. It is also used to prevent cross-site request forgery.

If you are using the Login with Amazon SDK for JavaScript, the above parameters are available in the response object provided by amazon.Login.authorize (an example is available in the Authorization Request section above).

Authorization Errors

If the user did not grant the request for access, or an error occurs, the authorization service will redirect the user-agent (a user's browser) to a URI specified by the client. That URI will contain error parameters detailing the error. For example:

HTTP/1.1 302 Found
Location: https://client.example.com/cb#error=access_denied
&state=208257577ll0975l93l2l59l895857093449424

The error parameters for a failed authorization request include:

Error Parameters	Description
`error`	An ASCII error code with an error code value.
`error_description`	A human-readable ASCII string with information about the error, useful for client developers.
`error_uri`	A URI to a web page with human-readable information about the error, useful for client developers.
`state`	The client `state` passed in the original authorization request.

The following error codes can be returned as the value for error:

Error Code	Description
`invalid_request`	The request is missing a required parameter, has an invalid value, or is otherwise improperly formed.
`unauthorized_client`	The client is not authorized to request an authorization code.
`access_denied`	The resource owner or authorization server denied this request.
`unsupported_response_type`	The request specified an unsupported response type. For this scenario, the `response_type` must be `code`.
`invalid_scope`	The client requested the wrong scope.
`server_error`	The authorization server encountered an unexpected error (treat as a 500 Internal Server HTTP error).
`temporarily_unavailable`	The authorization server is currently unavailable due to a temporary overload or scheduled maintenance (treat as a 503 Service Unavailable HTTP error).

Access Token Request

After the client (website) receives an Authorization Response with a valid authorization code, it can use that code to obtain an access token. With an access token, the client can read a customer profile.

To request an access token, the client makes a secure HTTP POST request to one of the following regional endpoints:

North America (NA) - https://api.amazon.com/auth/o2/token
European Union (EU) - https://api.amazon.co.uk/auth/o2/token
Far East (FE) - https://api.amazon.co.jp/auth/o2/token

Note: Applications are not region-specific. You can create, verify, and refresh tokens using any regional LWA endpoint, regardless of the region the application was created, the region of the customer, and the region in which the token was created.

Use the parameters listed in the table below for your POST request.

Parameter	Description
`grant_type`	REQUIRED. The type of access grant requested. Must be `authorization_code`.
`code`	REQUIRED. The code returned by the authorization request.
`redirect_uri`	REQUIRED. If you provided a `redirect_uri` for the authorization request, you must pass the same `redirect_uri` here. If you used the Login with Amazon SDK for JavaScript for the authorization request, you do not need to pass a `redirect_uri` here.
`client_id`	REQUIRED. The client identifier. This is set when you register your website as a client. For more information, see Client Identifier.
`client_secret`	OPTIONAL. The secret value assigned to the client during registration. You shouldn't use the client secret in Browser-Based apps because client secrets can't be reliably stored on web pages. When no `client_secret` is passed, no refresh token will be returned. Access token will still be returned if the `code_verifier` is valid.
`code_verifier`	RECOMMENDED. The same `code_verifier` that was used to generate the `code_challenge` in the Authorization Request. Required if `code_challenge` was used in the authorization request. For more information, see the PKCE RFC.

For example:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=authorization_code
&code=SplxlOBezQQYbYS6WxSbIA
&client_id=foodev
&client_secret=Y76SDl2F
&code_verifier=5CFCAiZC0g0OA-jmBmmjTBZiyPCQsnq_2q5k9fD-aAY

Note: The client_id and client_secret may be passed in the Authorization header instead, using HTTP Basic authentication. For more information, see RFC2617.

For example:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Authorization: Basic czzCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=authorization_code
&code=SplxlOBezQQYbYS6WxSbIA

To make a token request using the Login with Amazon SDK for JavaScript, you must set pkce as true in the options object used in the Authorize call. Then call amazon.Login.retrieveToken API with the authorization code returned in the authorization response from the Authorize API.

When pkce is set as true, and no code_challenge is specified, the SDK generates a code_verifier and code_challenge. The code_challenge is used in the authorization request. The code_verifier is stored in the amazon_Login_pkce_params cookie and used by the retrieveToken API in the token request to get the access token.

Cookies must be enabled and the retrieveToken call must be on the same domain as the authorize call. For more information, see retrieveToken API.

options = {}
options.scope = 'profile';
options.pkce = true;
amazon.Login.authorize(options, function(response) {
    amazon.Login.retrieveToken(response.code, callback);
    });

Access Token Response

When a client (website) makes a secure HTTP POST Authorization Request, the authorization server immediately returns the access token or an error in the HTTP response. For example:

HTTP/1.1 200 OK
 Content-Type: application/json;charset UTF-8
 Cache-Control: no-store
 Pragma: no-cache
 {
    "access_token":"Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX..."
 }

A successful response includes the following values:

Parameter	Description
`access_token`	The access token for the user account. Maximum size of 2048 bytes.
`token_type`	The type of token returned. Should be `bearer`.
`expires_in`	The number of seconds before the access token becomes invalid.
`refresh_token`	A refresh token that can be used to request a new access token. Maximum size of 2048 bytes.

Response parameters are encoded using the application/json media type. For more information, see RFC4627.

Access Token Errors

For some errors, the authorization service may return an HTTP 401 (Unauthorized) status code. This includes cases where the client passed the client_id and client_secret values in the Authorization header and the client could not be authenticated.

An unsuccessful response includes the following values:

Error Parameter	Description
`error`	An ASCII error code with an error code value.
`error_description`	A human-readable ASCII string with information about the error, useful for client developers.
`error_uri`	A URI to a web page with human-readable information about the error, useful for client developers.

The following error codes can be returned as the value for error:

Error Code	Description
invalid_request	The request is missing a required parameter, has an invalid value, or is otherwise improperly formed.
`invalid_client`	The client authentication failed. This is used in cases when the authorization service does not return an HTTP 401 (Unauthorized) status code.
`invalid_grant`	The authorization code is invalid, expired, revoked, or was issued to a different `client_id`.
`unauthorized_client`	The client is not authorized to use authorization codes. Can be caused by invalid code_verifier.
`unsupported_grant_type`	The client specified the wrong `token_type`.
`ServerError`	The server encountered a runtime error.

Using Refresh Tokens

Access tokens will expire after a set time period (normally returned in the expires_in parameter). When you obtain an access token, you will also receive a refresh token. You can use a refresh token to retrieve a new access token.

To submit a refresh token, the client makes a secure HTTP POST to https://api.amazon.com/auth/o2/token with the following parameters:

Parameter	Description
`grant_type`	REQUIRED. The type of access grant requested. Must be `refresh_token`.
`refresh_token`	REQUIRED. The refresh token returned by the original Access Token Response (described above).

For example:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Authorization: Basic czzCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=refresh_token
&refresh_token=Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX...

Note: The client_id and client_secret may be passed in the Authorization header instead, using HTTP Basic authentication. For more information, see RFC2617.

For example:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=refresh_token
&refresh_token=Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX...
&client_id=foodev
&client_secret=Y76SDl2F

The response to a refresh token submission is an Access Token Response.

Last updated: Dec 11, 2023