Developer Console

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

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.

  1. After the user logs in, send a request to the getEndpoint method using the following URI.
https://drive.amazonaws.com/drive/v1/account/endpoint
  1. 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

Support

If you have any questions, see the Developer Forum.


Last updated: Oct 30, 2020