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

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

Sign in to your Amazon Developer Console account.
From the top navigation, select Tools & Services > API Access.
Select the App Submission API.
This example shows the App Submission API
Click Create a new security profile.
Enter a security profile name and security profile description for your new profile, then click Save.
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

Navigate to the API Access page by selecting Tools & Services > API Access.
Click the API name to expand the panel.
Select the security profile that you created in the previous section from the drop-down list.
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:

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 an LWA Access Token. When you send requests to the API, set the Authorization header with a value of . 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.

Operation	HTTP method and URI
Register your app	`POST /{apiVersion}/applications/{appId}/devtest/register`
Add testers	`POST /{apiVersion}/applications/{appId}/tracks/{trackId}/testers`

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

Parameter	Located in	Description	Type	Required
`apiVersion`	Path	Version of the API, currently `v1`.	String	Yes
`appId`	Path	Identifier for the app. Example: `amzn1.devportal.mobileapp.dde7ec787b031584aa5f04606184041a`.	String	Yes
`access token`	Header	LWA token	String	Yes

Request body example

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

Request body properties

Parameter	Description	Type	Required
`packageName`	The package name of your app.	String	Yes
`certificate`	The certificate you will use to sign your app.	String	Yes

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

Parameter	Description	Type
`trackId`	Identifies the track for an app. For DevTest, the value is `devtest`.	String

HTTP status codes

Status	Description
`200 OK`	App successfully registered for DevTest.
`404 Not Found`	Requested resource not found.
`400 Bad Request`	Indicates that one or more properties in the request body aren’t valid or are absent.

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

Parameter	Located in	Description	Type	Required
`apiVersion`	Path	Version of the API, currently `v1`.	String	Yes
`appId`	Path	Identifier for the app. Example: `amzn1.devportal.mobileapp.dde7ec787b031584aa5f04606184041a`.	String	Yes
`access token`	Header	LWA token	String	Yes

Request body example

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

Request body properties

Parameter	Description	Type	Required
`groups`	List of tester groups.	List<TesterGroup>	Yes
`name`	Name of the tester group.	String	Yes
`testers`	List of testers.	List<Tester>	Yes
`firstName`	Tester’s first name.	String	No
`lastName`	Tester’s last name.	String	No
`email`	Tester’s email address.	String	Yes

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

Parameter	Description	Type
`groups`	List of tester group names added to the DevTest registration for this app.	List<String>
`uniqueTesterCount`	The number of unique testers added across tester groups.	Integer

HTTP status codes

Status	Description
`200 OK`	Testers successfully added to DevTest for the app.
`404 Not Found`	Requested resource not found.
`400 Bad Request`	Indicates that one or more properties in the request body aren’t valid or are absent.

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
    }]
}

Parameter	Description	Type
`name`	Name of the tester group.	String
`testers`	List of testers.	List<Tester>

Tester object

The Tester object contains the tester details.

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

Parameter	Description	Type
`firstName`	Tester’s first name.	String
`lastName`	Tester’s last name.	String
`email`	Tester’s email address.	String

​Base URL

​Authentication

​Create a security profile

​Associate the security profile with the API

​Request an LWA access token

​Send a token request

​Save the response

​Handle any error responses

​How to use the access token

​Operations

​Register your app

​Request

​Request example

​Request parameters

​Request body example

​Request body properties

​Response

​Response body example

​Response body properties

​HTTP status codes

​Add testers to DevTest for IAP

​Request

​Request example

​Request parameters

​Request body example

​Request body properties

​Response

​Response body example

​Response body properties

​HTTP status codes

​Object definitions

​TesterGroup object

​Tester object

Base URL

Authentication

Create a security profile

Associate the security profile with the API

Request an LWA access token

Send a token request

Save the response

Handle any error responses

How to use the access token

Operations

Register your app

Request

Request example

Request parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Add testers to DevTest for IAP

Request

Request example

Request parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Object definitions

TesterGroup object

Tester object