Requesting Scopes as Essential/Voluntary
The authorization requests as mentioned in the Implicit Grant and Authorization Code Grant can be modified to also include the essential/voluntary override information for the requested scopes. This will govern whether the Login With Amazon's consent page will allow customers to make changes to the requested scopes before granting consent. This information is specified using the scope_data parameter in the authorization request.
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:
| 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. |
| scope_data | OPTIONAL. URL encoded JSON blob with scope as the key and value as the essentiality for the requested scopes. See the examples below. |
| response_type | REQUIRED. The type of response requested. Can be code or token (deprecated). |
| 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. |
For example:
https://www.amazon.com/ap/oa?client_id=foodev
&scope=profile%20postal_code
&scope_data=%7B%22profile%22%3A%7B%22essential%22%3Atrue%7D%2C%22
postal_code%22%3A%7B%22essential%22%3Afalse%7D%7D
&response_type=code
&state=208257577ll0975l93l2l59l895857093449424
&redirect_uri=https://client.example.com/auth_popup/token
Where the scope parameter is url encoded version of "profile postal_code" and scope_data is a url encoded version of "{"profile":{"essential":true}, "postal_code":{"essential":false}}" The essential property for every scope can be set to either true or false. 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.
options = {} ;
options.scope = 'profile postal_code';
options.scope_data = {
'profile' : {'essential': true},
'postal_code' : {'essential': false}
};
options.response_type='code';
amazon.Login.authorize(options, function(response) {
if ( response.error ) {
alert('oauth error ' + response.error);
return;
}
<!-- Handle the response -->
});
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+postal_code
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.
Errors can be handled in the same way as mentioned in Authorization Code Grant section.