Private Skill Distribution API Reference

Use the Private Skill Distribution 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).

Operations

The Private Skill Distribution API includes the following operations.

Operation HTTP Method and URI

Add an account to the distribution list of a private skill

PUT /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts/{accountId}

Remove an account from the distribution list of a private skill

DELETE /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts/{accountId}

List the accounts in the distribution list of a private skill

GET /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts

Add an account to the distribution list of a private skill

Adds an account to the distribution list of the specified private skill. After you successfully 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 /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts/{accountId} resource.

Request header example

Copied to clipboard.

PUT /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts/{accountId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

skillId

Skill ID of the private skill to which to add the account to the distribution list.

String

Yes

stage

Stage of the private skill. Valid values: live and development.

String

Yes

accountId

Amazon Resource Name (ARN) for an AWS account that you want to grant access to the private skill. When you provide this value, use the exact ARN format: arn:aws:iam::<account ID>:root. For example, if the AWS account ID is 111122223333, you provide arn:aws:iam::111122223333:root. You must specify the root and not an individual user for that account.

String

Yes

access token

LWA token.

String

Yes

Request body example

The request has no body.

Request parameters

The request has no body.

Response

A successful response returns HTTP 204.

Response body example

The response has no body.

Response body parameters

The response has no body.

HTTP status codes

Status Description

204 Success

Account added to the distribution list for the private skill.

400 Bad Request

Server can't process the request due to a client error.

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.

404 Not Found

The requested resource isn't found.

429 Too Many Requests

You exceeded the permitted rate limit (specified number of requests per unit of time).

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Remove an account from the distribution list of a private skill

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 /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts/{accountId} resource.

Request header example

Copied to clipboard.

DELETE /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts/{accountId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

skillId

Skill ID of the private skill from which to delete the account from the distribution list.

String

Yes

stage

Stage of the private skill. Valid values: live and development.

String

Yes

accountId

Amazon Resource Name (ARN) for the AWS account to delete from the distribution list of the private skill. When you provide this value, use the exact ARN format: arn:aws:iam::<account ID>:root. For example, if the AWS account ID is 111122223333, you provide arn:aws:iam::111122223333:root. You must specify the root and not an individual user for that account.

String

Yes

access token

LWA token.

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.

Response body example

The response has no body.

Response body parameters

The response has no body.

HTTP status codes

Status Description

204 Success

Account deleted from the distribution list for the private skill.

400 Bad Request

Server can't process the request due to a client error.

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.

404 Not Found

The requested resource isn't found.

429 Too Many Requests

You exceeded the permitted rate limit (specified number of requests per unit of time).

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List the accounts in the distribution list of a private skill

List the accounts in the distribution list of a private skill.

Request

To list distribution accounts, you make a GET request to the /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts resource.

Request header example

Copied to clipboard.

GET /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

skillId

Skill ID of the private skill for which to list the distribution accounts.

String

Yes

stage

Stage of the private skill. Valid values: live and development.

String

Yes

nextToken

Token that you use to get more items in the list, after you receive a response with truncated results. Set this value to the value of nextToken from the truncated response you just received.

String

No

maxResults

Maximum number of items to return in the response.

String

No

access token

LWA token.

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, along with a list of distribution accounts.

Response body example

The following example shows a response.

{
   "privateDistributionAccounts": [
      {
         "principal": "111122223333",
         "acceptStatus": "ACCEPTED"
      },
      {
         "principal": "444455556666",
         "acceptStatus": "PENDING"
      }
   ],
   "nextToken": "12345"
}

Response body parameters

Parameter Description Type

privateDistributionAccounts

List of accounts on the distribution list of the private skill.

Array

principal

Account that is on the distribution list of the private skill.

String

acceptStatus

Enterprise IT administrator's action on the private skill distribution.

String

nextToken

Value to use for the nextToken parameter in a subsequent request.

String

HTTP status codes

Status Description

200 Success

Response body contains a list of distribution accounts associated with the private skill.

400 Bad Request

Server can't process the request due to a client error.

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The requested operation isn't allowed.

404 Not Found

The requested resource isn't found.

429 Too Many Requests

You exceeded the permitted rate limit (specified number of requests per unit of time).

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.