RESTful API Getting Started

Important: Amazon Drive has been deprecated! No apps using Amazon Drive can be submitted to the Appstore.

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.

Implicit Grant - Send a client_id to get an access_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 a client_secure to get an access_token and a refresh_token.
- Advantage: More secure. Indefinite access by using the refresh_token.
- Disadvantage: Requires server-side scripting. More difficult to implement.

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.

Note: You must generate a new 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

Note: The response to the 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