Developer Console
Sign In
Sign In
Developer Console

API Authentication

You need to configure access to the App Submission API before you can use it. Follow these steps:

  1. Create a Security Profile using the Appstore Developer Console.
  2. From the API Access Page, associate your new security profile with the App Submission API.
  3. Request an access token using the Login With Amazon API. You add the token to the HTTP header in each API request.

Create a Security Profile

To use App Submission API, you need to create a security profile and request access to the API for this security profile. Security profile is the mechanism used to generate access tokens for API access.

To create a security profile, follow these steps:

  1. Login to your Amazon Developer Console account. You will be prompted to create an account if you do not already have one.
  2. In the main navigation, click Apps & Services.
  3. Click API Access in the sub-menu.

  4. Click the API name of the API.

    API Access page

  5. Click the Create a new security profile button.
  6. Enter a Security Profile Name and Security Profile Description for your new profile, then click Save.
  7. Save your Client ID and Client Secret (from the Web Settings tab), as you will need this information to access the API.
    Client ID and Client Secret

Associate Security Profile with the API

From the API Access Page, associate your new security profile with the App Submission API.

  1. Navigate to the API Access page.
  2. Click the API name to expand the panel.
  3. Select your new security profile from the drop-down list.
  4. Select Attach to associate the security profile with this API. The API name and attached security profile is added to the Security Profile(s) in use panel.
    Client ID and Client Secret

You can now use the client ID and client secret to request a Login With Amazon (LWA) access token.

Request LWA Access Token

With your client ID and client secret, use the Login With Amazon API to request a Login with Amazon access token by following these steps:

1. Send token request

Send a POST request to https://api.amazon.com/auth/o2/token with the following header and content:

  • Header: Content-Type: application/x-www-form-urlencoded
  • Content:
    • client_id: The client ID you saved in step 7 of Create a Security Profile.
    • client_secret: The client secret you saved in step 7 of Create a Security Profile.
    • grant_type: Set to client_credentials.
    • scope: Set the value to appstore::apps:readwrite.

Sample JSON content:

{
    "grant_type": "client_credentials",
    "client_id": "amzn1.application-oa2-client.ae941846cdd745e9a53319f7bb98d435",
    "client_secret": "41d135b2b02ce5f2fbf7643a66477c089fcc1d88d11f69d3e4a6285b917ca35d",    
    "scope": "appstore::apps:readwrite"
}

Sample cURL request:

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=amzn1.application-oa2-client.5c1462ee102c4a57a5224d0c72118741&client_secret=15d1829ddf4f12d1c5d425e57e5ca081d0f7a63bd94c9e142ff8b20d9de880a4&scope=appstore::apps:readwrite' https://api.amazon.com/auth/O2/token

2. Save the response

The response looks like this:

{"access_token":"Atc|MAEBIBav2tvCbJOA9Jv5sRpej6xY_qzHFuCpbWT-Z94nRqVWVcfmZVNPEhZiet-H3vdQcORqE5pO4fCKEi6kfvzzPtxHIoPIte-ZbKB1XgfjfJnciJHqnbV1UF4WJ_an1g9y7yvWKWJddQ2NLPO-C-Y71BPxJ0KDWOPonn_2qFLY5OJo3BhHKIwNHteQAwkCA9iko8d5tosS7fo3dvS-PFmiBk3OMUmr1AdYtuOnq1RVrX7-C14oWzfACudykTn5cDb48Qy2k6R70__GzHG3fC_-Rfzt7zwhfdBWpwoQk-GbV4Bes457oZwHz89Tj-AAf3DouYQ","scope":"appstore::apps:readwrite","token_type":"bearer","expires_in":3600}
  • access_token: The access token.
  • expires_in: The number of seconds until the access token expires.
  • scope: Will be appstore::apps:readwrite.
  • token_type: Will always be bearer.

3. Handle any error responses

If your token request results in an error, the response message body includes one of the following error messages:

Error message body Details
{"error_description":"Client authentication failed","error":"invalid_client"} Invalid secret key
{"error_description":"The request has an invalid parameter : scope","error":"invalid_scope"} Invalid scope value
{"error_description":"The authorization grant type is not supported by the authorization server","error":"unsupported_grant_type"} Incorrect authorization grant type
{"error_description":"The Content-Type is not supported by the authorization server","error":"invalid_request"} Unsupported content-type

How to use the access token

Save your access token, which is the access_token field in the response from Request LWA Access Token.

When you send requests to the App Submission APIs, set the Authorization header with a value of Bearer <YOUR_ACCESS_TOKEN>. The access token is a long string of characters beginning with "Atc|".

Sample cURL request:

curl -v -X GET "<endpoint URL>"   -H  "Authorization: Bearer Atc|MAEBIKfsULrH7jSzvJTV8UmiHWr9M86O3JRmv4t1hqoCBriSMEP5Gsey_FiBxteZ8oxGd6abGuOFga8fwnMhmSD_Sg4MI4odXLPgB2IVs8M1uswjuWjnsMcvehpWvf9tzQT8HTWiBigInJLB8BrMg5J3O02hlTvcF441XxXDXthyj993COJ2u5swOTKjC_dcijiN8amuzrj32rh9Fr3CNgCpoZ0WqXnBhoHUVMYSOBV-owA5rI4-OfysXC71Zbtv1hb8igk"

When the access token expires, obtain a new token by following the procedure in Request LWA Access Token and start using the new access token in your requests. You will know your access token has expired if it has been over an hour since you last requested an access token and you start getting 403 Forbidden HTTP errors with a message that says "Request is not authorized."

Last updated: Jan 26, 2023