Private Skill Distribution REST API Reference
Use the Private Skill Distribution REST API to manage the distribution list of a private Alexa skill. A distribution list specifies the accounts that have permission to access the skill.
API endpoint
The endpoint of the Private Skill Distribution API is https://api.amazonalexa.com
.
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.
Operations
The Private Skill Distribution API includes the following operations.
Operation | HTTP Method and URI |
---|---|
| |
| |
|
Add account to the distribution list
Adds an account to the distribution list of the specified private skill. After you add the account to the distribution list, the specified account has permission to access the private skill.
Request
To add an account to the distribution list of a private skill, you make a PUT
request to the privateDistributionAccounts
resource.
Request header example
PUT /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts/{accountId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the private skill. |
String |
Yes |
|
Path |
Indicates stage of the private skill. |
String |
Yes |
|
Path |
Amazon Resource Name (ARN) for an AWS account that you want to grant access to the private skill. You must specify the root and not an individual user for that account. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request parameters
The request has no body.
Response
A successful response returns HTTP 204 No Content
.
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
The response has no body.
Response body parameters
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Account added to the distribution list for the private skill. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List accounts on the distribution list
List the accounts on the distribution list of a private skill.
Request
To list distribution accounts, you make a GET request to the privateDistributionAccounts
resource.
Request header example
GET /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts?nextToken={nextToken}&maxResults={maxResults}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the private skill. |
String |
Yes |
|
Path |
Indicates stage of the private skill. |
String |
Yes |
|
Query |
Token from the previous response. |
String |
No |
|
Query |
Maximum number of results to return in the response. |
Number |
No |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request body has no body.
Request body parameters
The request body has no body.
Response
A successful response returns HTTP 200 OK
, along with a list of distribution accounts.
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
{
"privateDistributionAccounts": [
{
"principal": "111122223333",
"acceptStatus": "ACCEPTED"
},
{
"principal": "444455556666",
"acceptStatus": "PENDING"
}
],
"nextToken": "someToken.1",
"_links": {
"self": {
"href": "v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts"
},
"next": {
"href": "v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts?nextToken=someToken.1&maxResults=10"
}
}
}
Response body parameters
Parameter | Description | Type |
---|---|---|
|
List of accounts on the distribution list of the private skill. |
Array of objects |
|
ARN of the account. |
String |
|
Enterprise IT administrator's action on the skill distribution. |
String |
|
Identifies the next set of accounts to return. The token expires in 24 hours. |
String |
|
Links for item navigation. |
_links object |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of distribution accounts associated with the private skill. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Remove account from the distribution list
Removes an account from the distribution list of the specified private skill.
Request
To remove an account from the distribution list, you make a DELETE
request to the privateDistributionAccounts
resource.
Request header example
DELETE /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts/{accountId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the private skill. |
String |
Yes |
|
Path |
Indicates stage of the private skill. |
String |
Yes |
|
Path |
Amazon Resource Name (ARN) for an AWS account that you want to grant access to the private skill. You must specify the root and not an individual user for that account. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body parameters
The request has no body.
Response
A successful response returns HTTP 204 No Content
.
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
The response has no body.
Response body parameters
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Account deleted from the distribution list for the private skill. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off. |
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
Last updated: Sep 08, 2023