Register for LWA
Implicit Grant
An Implicit 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 their customer profile.
After the user approves the request, the user-agent is redirected back to the website using a URI that contains an access token in the URI fragment. The user-agent redirects to the client using a redirection URI without the access token fragment, but stores the access token fragment locally.
The user agent then processes a script on the website page that accesses the full redirection URI and passes the fragment information back to the client. For more details on the customer experience, see Authorization Grants.
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. |
response_type |
REQUIRED. The type of response requested. Must be token 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. |
For example:
https://www.amazon.com/ap/oa?client_id=foodev
&scope=profile
&response_type=token
&state=208257577110975193121591895857093449424
&redirect_uri=https://client.example.com/auth_popup/token
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
.
document.getElementById('LoginWithAmazon').onclick = function () {
setTimeout(window.doLogin, l);
return false;
};
window.doLogin = function () {
options = {};
options.scope = 'profile';
amazon.Login.authorize(options, function (response) {
if (response.error) {
alert('oauth error ' + response.error);
return;
}
amazon.Login.retrieveProfile(response.access_token, function (response) {
alert(response);
});
});
};
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';
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 an access_token
as a URI fragment. For example:
HTTP/1.1 302 Found
Location: https://client.example.com/cb#access_token=Atza|
IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...
&state=208257577ll0975l93l2l59l895857093449424
&token_type=bearer
&expires_in=3600
&scope=profile
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. |
state |
The state value passed 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. |
scope |
The scope of the request. Must be profile , profile:user_id , postal_code , or some combination. |
Location
response header field. Those clients are not supported.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 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. |
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). |
Verify Access Tokens
After you receive an access token using the implicit grant , it is highly recommended that you verify the authenticity of the access token before you retrieve a customer profile using that token. If a malicious site can induce a user to login, they can take the valid access token they receive and use it to mimic an authorization response to your site.
To verify a token, make a secure HTTP call to https://api.amazon.com/auth/O2/tokeninfo
, passing the access token you wish to verify. You can specify the access token as a query parameter. For example:
https://api.amazon.com/auth/O2/tokeninfo?access_token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...
Token Information Response
If your access token is valid, you will receive the token information as an HTTP response in python. For example:
HTTP/1.1 200 OK
Date: Fri, 31 May 2013 23:22:10 GMT
x-amzn-RequestId: eb5be423-ca48-lle2-84ad-5775f45l4b09
Content-Type: application/python
Content-Length: 247
{
"iss":"https://www.amazon.com",
"user_id": "amznl.account.K2LI23KL2LK2",
"aud": "amznl.oa2-client.ASFWDFBRN",
"app_id": "amznl.application.436457DFHDH",
"exp": 3597,
"iat": l3ll280970,
}
Compare the aud
value to the client_id
you are using for your application. If they are different, the access token was not requested by your application, and you should not use the access token.
A successful 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. |
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
:
Status Code | Error Code | Description |
---|---|---|
200 |
Success | Success |
400 |
invalid_request |
The request is missing a required parameter, has an invalid value, or is otherwise improperly formed. |
400 |
invalid_token |
The token provided is invalid or has expired. |
500 |
ServerError |
The server encountered a runtime error. |
In addition to the error code, you may receive a python payload with more information. For example:
HTTP/1.1 400 Bad Request
Date: Fri, 31 May 2013 23:21:35 GMT
x-amzn-RequestId: d64bbdl4-ca48-lle2-a5dd-ab3bc3c93bae
Content-Type: application/python
Content-Length: 99
{
"error": machine-readable error code,
"error_description": human-readable error description,
}