RESTful API Getting Started
Authorizing Your App
For more information about authorizing your app and requesting an access token, see the Access Token section of the Login with Amazon documentation.
Login with Amazon supports two types of authorization.
- Implicit Grant - Send a
client_id
to get anaccess_token
.- Advantage: Easier to implement. Only relies on client-side scripting. Example: javascript
- Disadvantage: The access token expires.
- Authorization Code Grant - Send a
client_id
and aclient_secure
to get anaccess_token
and arefresh_token
.- Advantage: More secure. Indefinite access by using the
refresh_token
. - Disadvantage: Requires server-side scripting. More difficult to implement.
- Advantage: More secure. Indefinite access by using the
If you are not able to implement server-side scripting, then using the implicit grant is your only choice. If you are able to implement server-side scripting, then using the authorization code grant is recommended.
access_token
after it expires in 1 hour. That is also true for sending a request to any endpoint since the access_token
validity is required. When you send a request for an access_token
, the response only contains access token related content. If you are retrieving customer profile data, such as name and email address, then you must use the access token in your response, since it has provides access to customer profile data. Obtaining the customer profile data requires you to send a request to the api.amazon.com/user/profile
endpoint.Implicit Grant
Redirect the user to the Login with Amazon API using the following URI.
https://www.amazon.com/ap/oa
Query Parameters:
Use the following parameters in the redirect. All of the parameter values must be url-encoded.
Parameter | Description |
---|---|
client_id |
The identifier for the app. |
scope (Permission Level) |
See Scopes and Permissions and choose the scope you want to get permission for. You can request only those scopes where your app has been added to the allow list. You can also concatenate multiple scopes together. For example, clouddrive%3Aread_image%20clouddrive%3Awrite |
response_type |
token : Specified for implicit grant only. |
redirect_uri |
Specifies one of the return URIs that you added to your app when signing up. |
Sample Request:
https://www.amazon.com/ap/oa?client_id=amzn1.application-oa2-client.b91a4d2fd2f641f2a15ea469&scope=clouddrive%3Aread_all%20clouddrive%3Awrite[Implicit Grant Type code removed]&redirect_uri=http://localhost
After the user is authenticated, the user is redirected to the URI that you provided with access_token
in the redirect_uri
parameter.
Sample Response:
http://localhost/#access_token=Atza%7CIQEBLjAsAhQhzDgHuUPvSgvM&token_type=bearer&expires_in=3600&scope=clouddrive%3Aread_all+clouddrive%3Awrite
By using implicit grant, the user is redirected to a page with a log-in form and a list of scope descriptions that the user must either grant access to all or none of the scopes. If the customer provides consent, then the access_token
is generated. All subsequent requests to the API should be sent with a valid access token. For more information including how to use Login with Amazon with iOS and Android apps, see Amazon Drive SDK for iOS and .
Run html_decode
on the access_token
in the response (azta%7C... --> azta|...)
, and pass the value into the request header for all requests to the Amazon Drive API.
Authorization Code Grant
Redirect customer to Login with Amazon and obtain code. Redirect the user to the Login with Amazon API using the following URI.
https://www.amazon.com/ap/oa
Query Parameters
Use the following parameters in the redirect. All of the parameter values must be url-encoded.
Parameter | Description |
---|---|
client_id |
The identifier for the app. |
scope (Permission Level) |
See Scopes and Permissions and choose the scope you want to get permission for. You can request only those scopes where your app has been added to the allow list. You can also concatenate multiple scopes together. For example: clouddrive%3Aread_image%20clouddrive%3Awrite |
response_type |
code : Specified for authorization code grant only. |
redirect_uri |
Specifies one of the return URIs that you added to your app when signing up. |
Sample Request
https://www.amazon.com/ap/oa?client_id=amzn1.application-oa2-client.b91a4d2fd2f641f2a15ea469scope=clouddrive%3Aread_all%20clouddrive%3Awrite&response_type=code&redirect_uri=http://localhost
After the user logs in, the user is redirected to the URI that you provided with code in the redirect_uri
parameter.
Sample Response
http://localhost/?code=ANdNAVhyhqirUelHGEHA&scope=clouddrive%3Aread_all+clouddrive%3Awrite
Your service leverages the code returned to ask for an access_token
.
Send a RESTful POST request to retrieve the authorization code using an access_token
. POST specifies the endpoint.
https://api.amazon.com/auth/o2/token
HTTP Header Parameters
Parameter | Description |
---|---|
Content-Type |
Specifies the content type of the request. application/x-www-form-urlencoded |
HTTP Body Parameters
Parameter | Description |
---|---|
grant_type |
Specifies the grant type for the request: authorization_code |
code |
Specifies the code returned after user authorization. |
client_id |
Specifies the identifier for the app. This is a body parameter. |
client_secret |
Specifies the secret identifier associated with the app. |
redirect_uri |
Specifies one of the return URIs that you added to your app when signing up. |
Sample Request:
POST https://api.amazon.com/auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
grant_type=authorization_code&code=ANBzsjhYZmNCTeAszagk&client_id=amzn1.application-oa2-client.b91a4d2fd2f64&client_secret=6963038c1c2063c33ab9eedc0cf8&redirect_uri=http%3A%2F%2Flocalhost
Sample Response:
HTTP /1.1 200 OK
{
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EsdqwqwdqdasdvferrE",
"access_token": "Atza|IQEBLjAsAhRBejiZKPfn5HO2562GBt26qt23EA"
}
Your app is able to use the access_token
to send requests to the Amazon Drive API.
Use refresh_token
to obtain new access_token
when expired.
Send a RESTful POST request to retrieve the authorization code using a refresh_token.
POST : Specifies the endpoint.
https://api.amazon.com/auth/o2/token
HTTP Header Parameters:
Parameter | Description |
---|---|
Content-Type |
Specifies the content type of the request: application/x-www-form-urlencoded |
HTTP Body Parameters:
Parameter | Description |
---|---|
grant_type |
Specifies the grant type for the request: refresh_token |
refresh_token |
Specifies the refresh token returned with the last request for a new access token. This is a body parameter. |
client_id |
Specifies the identifier for the app. |
client_secret |
Specifies the secret identifier associated with the app. |
Sample Request
POST https://api.amazon.com/auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
grant_type=refresh_token&refresh_token=Atzr%7CIQEBLzAtAhUAibmh-1N0E&client_id=amzn1.application-oa2-client.b91a4d2fd2f6&client_secret=6963038c1c2063c33ab9eedc0cf822
Sample Response
HTTP /1.1 200 OK
{
"token_type": "bearer",
"expires_in": 3600,
"refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EVztZJofMx",
"access_token": "Atza|IQEBLjAsAhQ3yD47Jkj09BfU_qgNk4"
}
By using authorization code grant, the user is redirected to a page with a log-in form and a list of scope descriptions, and the user is able to either grant access to all or none of the scopes. If the user provides consent, then the authorization code is generated. Your service must delegate the user sending the request to Login with Amazon in order to retrieve an access_token
, and then all subsequent requests to the API must be sent with a valid access token. For more information about how to use Login with Amazon in iOS and Android apps, see the Platform Resources section of the Login with Amazon documentation.
API Requirements
Common HTTP Headers in a Request
Header | Description |
---|---|
Authorization | The information required for request authentication. For more information about how to get the access token, see the Platform Resources section of the Login with Amazon documentation. The Authorization header should contain and specify the "Bearer " + authorizationToken.
Example:
java
HttpGet request = new HttpGet(url);
request.addHeader("Authorization", "Bearer " + authorizationToken);
|
Content-Length | Specifies the length of the message in the body; without the headers. This is a required parameter when the body of the request in not empty. |
Content-Type | Specifies the content type of the resource being requested.
Example: application/json
Example: multipart/form-data
|
Accept-Encoding | Specifies the type of encoding returned in the response. **Example**: gzip |
user-agent | Specifies the version of device software sending the request. **Example**: Photos/3.2.5004610 (IML74K) |
Standards
UTF-8 encoding
The strings sent in a request or a response must be encoded as UTF-8.
Date format
The dates created by the system are in dateTime ISO 8601 format.
Example: 2014-03-07T22:31:12.173Z
MD5 format
The MD5 hash for the file must be encoded in hexadecimal.
Endpoints
The master API endpoint for Amazon is the following.
https://drive.amazonaws.com
To obtain the correct endpoint for each user, follow these steps.
- After the user logs in, send a request to the
getEndpoint
method using the following URI.
https://drive.amazonaws.com/drive/v1/account/endpoint
- The response from Amazon Drive returns the following parameters, which are used in new requests.
metadataUrl
: Specifies the URI for the read and write metadata of nodes.contentUrl
: Specifies the URI for uploading and downloading files
getEndpoint
request for each customer should be cached for three to five days. You should not send a getEndpoint
method request daily.Support
If you have any questions, see the Developer Forum.
Last updated: Oct 30, 2020