Developer Console

Authorization Code Grant

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

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

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');

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.

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).

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

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

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...

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