App Submission API for Testing

The App Submission API for Testing is a REST API that lets you programmatically register your app for Appstore DevTest and add testers.

Before using the API, you must set up access and obtain an OAuth session token, which you'll include in the HTTP header of each API request.

• Base URL
• Authentication
• Operations
• Register your app
• Add testers to DevTest for IAP
• Object definitions

Base URL

The base URL of the App Submission API for Testing is developer.amazon.com/api/appstore.

Authentication

To configure access to the App Submission API for Testing, you must first create a security profile and associate it with the API in the Developer Console. Then, request an access token using the Login With Amazon API and add the token to the HTTP header in each API request.

Create a security profile

Before you can use the API, you must create a security profile. A security profile generates access tokens, which you use to access the API.

To create a security profile

1. Log in to your Amazon Developer Console account.
2. From the top navigation, select Apps & Services > API Access.

3. Select the App Submission API.

   

4. Click Create a new security profile.
5. Enter a security profile name and security profile description for your new profile, then click Save.
6. From the Web Settings tab, save your client ID and client secret as you need this information to access the API.

   

Associate the security profile with the API

After you create the security profile, you must associate it with the API in the Developer Console.

To associate the security profile with the API

1. Navigate to the API Access page by selecting Apps & Services > API Access.
2. Click the API name to expand the panel.
3. Select the security profile that you created in the previous section 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.

   

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

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

Send a 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 the final step of Create a Security Profile.
  • client_secret: The client secret you saved in the final step 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.<your-client-id>",
    "client_secret": "<your-client-secret>",
    "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.<your-client-id>&client_secret=<your-client-secret>&scope=appstore::apps:readwrite' https://api.amazon.com/auth/O2/token

Save the response

The following is an example response.

{
    "access_token": "Atc|MAEBI...",
    "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: Always appstore::apps:readwrite.
• token_type: Always bearer.

Handle any error responses

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

How to use the access token

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

When you send requests to the API, 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 an 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."

Operations

The App Submission API for Testing includes the following operations.

Register your app

Registers your app for Appstore DevTest for In-App Purchasing (IAP).

Request

To register your app for Appstore DevTest for IAP, you make a POST request to the /{apiVersion}/applications/{appId}/devtest/register endpoint. In the request body, provide your app's package name and the certificate you will use to sign the app.

Request example

POST /{apiVersion}/applications/{appId}/devtest/register
Host: developer.amazon.com/api/appstore
Content-Type: application/json
Authorization: Bearer {access token}

Request parameters

Request body example

{
    "packageName": String,
    "certificate": String
}

Request body properties

Response

A successful response returns HTTP 200 OK, along with the trackId, which you'll use in the add testers request. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human-readable message.

Response body example

{
    "trackId": "devtest"
}

Response body properties

HTTP status codes

Add testers to DevTest for IAP

Adds testers to the DevTest environment for IAP testing.

Request

To add testers to DevTest for IAP, you make a POST request to the /{apiVersion}/applications/{appId}/tracks/{trackId}/testers endpoint. In the request, you must use the trackId returned in the registration response. You must also specify the tester group names that you want to add your testers to, and provide the tester details.

Request example

POST /{apiVersion}/applications/{appId}/tracks/{trackId}/testers
Host: developer.amazon.com/api/appstore
Content-Type: application/json
Authorization: Bearer {access token}

Request parameters

Request body example

{
    "groups": [{
        "name": String,
        "testers": [{
            "firstName": String,
            "lastName": String,
            "email": String
        }]
    }]
}

Request body properties

Response

A successful response returns HTTP 200 OK and includes a list of the tester groups added and the number of unique testers across the groups. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human-readable message.

Response body example

{
    "groups": List<String>,
    "uniqueTesterCount" : Integer
}

Response body properties

HTTP status codes

Object definitions

The App Submission API for Testing uses the following objects.

TesterGroup object

The TesterGroup object contains the name of the tester group and a list of testers.

{
    "name": String,
    "testers": [{
        "firstName": String,
        "lastName": String,
        "email": String
    }]
}

Tester object

The Tester object contains the tester details.

{
    "firstName": String,
    "lastName": String,
    "email": String
}

Last updated: Sep 30, 2025