SSL Certificates REST API Reference

Use the SSL Certificates REST API to create a self-signed SSL certificate to test your custom skill with your web service. Alexa communicates with your web service by using HTTPS and requires an SSL certificate. For more details, see Configure Your Web Service to Use a Self-signed Certificate.

For more details about web service hosting, see Host a Custom Skill as a Web Service.

API endpoint

The endpoint of the SSL Certificates 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 SSL Certificates API includes the following operations.

Operation HTTP method and URI

Get certificates

GET /v1/skills/{skillId}/sslCertificateSets/~latest

Set certificates

PUT /v1/skills/{skillId}/sslCertificateSets/~latest

Get certificates

Get the SSL certificates from the skill manifest associated with the specified skill.

Request

To get the certificates, you make a GET request to the /v1/skills/{skillId}/sslCertificateSets resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/sslCertificateSets/~latest
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

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

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with SSL certificates. 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

{
  "sslCertificate": "{certificateValue}",
  "regions": {
    "NA": {
      "sslCertificate": "{certificateValue}"
    },
    "EU": {
      "sslCertificate": "{certificateValue}"
    },
    "FE": {
      "sslCertificate": "{certificateValue}"
    }
  }
}

Response body properties

Property Description Type

sslCertificate

Default SSL certificate for the skill.

String

regions

(Optional) Regional SSL certificates that override the default certificate, if specified.

Map

regions.<region>

Two-letter code for the geographic region. Valid values: NA, EU, FE, IN.

Object

regions.<region>.sslCertificate

SSL certificate for the specified region.

String

HTTP status codes

Status Description

200 OK

Response body contains SSL certificates defined in the skill manifest.

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 code 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

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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.

Set certificates

Update the SSL certificates in the skill manifest associated with the specified skill. You can only set certificates if the certificate type for the endpoint is SelfSigned. For more details, see Skill Manifest / Endpoint.

Request

To update a certificate, you make a PUT request to the /v1/skills/{skillId}/sslCertificateSets resource.

Request path and header example

Copied to clipboard.

PUT /v1/skills/{skillId}/sslCertificateSets/~latest
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

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

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
  "sslCertificate": "{certificateValue}",
  "regions": {
    "NA": {
      "sslCertificate": "{certificateValue}"
    },
    "EU": {
      "sslCertificate": "{certificateValue}"
    },
    "FE": {
      "sslCertificate": "{certificateValue}"
    }
  }
}

Request body properties

Property Description Type Required

sslCertificate

Default SSL certificate for the skill.

String

Yes

regions

Regional SSL certificates that override the default certificate, if specified.

Map

No

regions.<region>

Two-letter code for the geographic region. Valid values: NA, EU, FE, IN.

Object

Yes

regions.<region>.sslCertificate

SSL certificate for the specified region.

String

Yes

Response

A successful response returns 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 properties

The response has no body.

HTTP status codes

Status Description

200 OK

Skill manifest updated with new certificate values successfully.

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 code 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

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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: Aug 01, 2024