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

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

List accounts on the distribution list

GET /v1/skills/{skillId}/stages/{stage}/privateDistributionAccounts?nextToken={nextToken}&maxResults={maxResults}

Remove account from the distribution list

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

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

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 Located in Description Type Required

skillId

Path

Identifies the private skill.
Valid values: 1–255 characters.

String

Yes

stage

Path

Indicates stage of the private skill.
Valid values: development, live.

String

Yes

accountId

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.
Valid value: ARN format: arn:aws:iam::<account ID>:root.
For example, if the AWS account ID is 111122223333, you provide arn:aws:iam::111122223333:root.

String

Yes

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property from the LaunchRequest or IntentRequest.

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

204 Success

Account added to the distribution list for the private skill.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

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.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

skillId

Path

Identifies the private skill.
Valid values: 1–255 characters.

String

Yes

stage

Path

Indicates stage of the private skill.
Valid values: development, live.

String

Yes

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–50. Default: 50.

Number

No

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property from the LaunchRequest or IntentRequest.

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

privateDistributionAccounts

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

Array of objects

privateDistributionAccounts[].principal

ARN of the account.

String

privateDistributionAccounts[].acceptStatus

Enterprise IT administrator's action on the skill distribution.
Valid values: ACCEPTED, PENDING.

String

nextToken

Identifies the next set of accounts to return. The token expires in 24 hours.
Use this value for the nextToken parameter in a subsequent request.

String

_links

Links for item navigation.
Defined in JSON Hypertext Application Language specification.

_links object

HTTP status codes

Status Description

200 Success

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

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

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.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

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 Located in Description Type Required

skillId

Path

Identifies the private skill.
Valid values: 1–255 characters.

String

Yes

stage

Path

Indicates stage of the private skill.
Valid values: development, live.

String

Yes

accountId

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.
Valid value: ARN format: arn:aws:iam::<account ID>:root.
For example, if the AWS account ID is 111122223333, you provide arn:aws:iam::111122223333:root.

String

Yes

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property from the LaunchRequest or IntentRequest.

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

204 No Content

Account deleted from the distribution list for the private skill.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

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.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

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

Was this page helpful?

Last updated: Sep 08, 2023