Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

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.

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

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';
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 an
  access token. The Javascript SDK does not support this step
  because it would expose the client secret. -->
});

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. For example:

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

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 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 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 REQUIRED. The secret value assigned to the client during registration.

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

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

The Login with Amazon SDK for JavaScript does not contain a function for exchanging authorization codes for access tokens. This is because that exchange requires the client secret, which should not be stored in a script. As a result, your web server will need to make the exchange instead. If you use amazon.Login.authorize to request an authorization code, you should pass the authorization code to your server, or use a redirect_uri that will be handled by server-side code.

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