Certificate Authority Management REST API Reference
Use the Certificate Authority Management REST API to connect your Alexa devices to WPA2 Extensible Authentication Protocol (EAP) Transport Layer Security (TLS) networks. With this API, you create a private certificate authority (CA), import a signed CA certificate, and then let Alexa Smart Properties (ASP) issue and rotate certificates that enable your endpoints to join your WPA2-EAP Enterprise Wi-Fi networks.
Before you can use the Certificate Authority Management API, visit the Alexa Smart Properties management console and request the WPA2 Enterprise Wi-Fi add-on package. For more details about getting started, see WPA2 Enterprise Wi-Fi.
API endpoint
The endpoint of the Certificate Authority Management 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 Manage API Access.
Access to consent information is based on the permission scopes enabled for your skill and granted by the customer. Include the following permission scope when you request an access token.
Permission scope | Description |
---|---|
|
Allows your skill to access the WPA2 Enterprise Wi-Fi add-on. |
|
Operations
The Certificate Authority Management API includes the following operations.
Operation | HTTP Method and URI |
---|---|
| |
| |
| |
| |
| |
|
Create certificate authority
Create a private certificate authority (CA) to issue certificates to ASP endpoints so that the endpoints can join WPA2-EAP Enterprise Wi-Fi networks securely.
After you create the CA, get the Certificate Signing Request (CSR) with Get certificate authority details, and then use the CSR to get a CA certificate from your RADIUS server.
HTTP 429 Too Many Requests
, implement back-off logic to support two to three second gaps for retries of CA creation.Request
To create the CA, you make a POST
request to the /v1/enterprise/certificateAuthorities
resource.
Request path and header example
POST /v1/enterprise/certificateAuthorities HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"friendlyName": {
"type": "PLAIN",
"value": {
"text": "Customer Network #1"
}
},
"rotationPeriod": {
"value": 6,
"interval": "MONTHS"
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Name of the new CA. |
|
Yes |
|
Specifies how often to rotate certificates on endpoints. |
Object |
Yes |
|
Defines the rotation period. |
Integer |
Yes |
|
Defines the rotation interval. |
String |
Yes |
Response
A successful response returns HTTP 201 OK
, along with the ID of the new private CA.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.
Response body example
{
"id": "amzn1.alexa.enterprise.certificateAuthority.did.1"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Unique, encrypted ID of the new private CA. |
String |
HTTP status codes
For error responses, see Error types.
Status | Description |
---|---|
|
Response body contains the ID of the new private CA. |
|
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. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete certificate authority
Delete the specified private CA that's no longer in use. Certificates that the CA issued to devices before you delete the CA remain valid until you remove the certificate authority certificate from the trust store for your RADIUS server.
Request
To delete a CA, you make a DELETE
request to the /v1/enterprise/certificateAuthorities/{certificateAuthorityId}
resource.
Request path and header example
DELETE /v1/enterprise/certificateAuthorities/{certificateAuthorityId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID of the private CA to delete. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
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 object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
CA deleted successfully. |
|
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. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get certificate authority details
Get the details, including the status and the Certificate Signing Request (CSR), of the specified CA. The CSR is the prerequisite for your RADIUS server to sign a certificate for the new CA.
Request
To get the details of a CA, you make a GET
request to the /v1/enterprise/certificateAuthorities/{certificateAuthorityId}
resource.
Request path and header example
GET /v1/enterprise/certificateAuthorities/{certificateAuthorityId}?expand={expand} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID of the private CA. |
String |
Yes |
|
Query |
Get expanded information about the certificate authority. |
String |
No |
|
Header |
Access token for the customer. |
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 certificate details for the specified CA.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.
Response body example
{
"id": "amzn1.alexa.enterprise.certificateAuthority.did.1",
"friendlyName": {
"type": "PLAIN",
"value": {
"text": "Customer Network #1"
}
},
"status": "ACTIVE",
"createdAt": "2024-03-15T12:10:00Z",
"updatedAt": "2024-03-15T12:10:00Z",
"csr": "-----BEGIN CERTIFICATE REQUEST-----CERTIFICATE_REQUEST_CONTENT-----END CERTIFICATE REQUEST-----",
"certificateMetadata": {
"certificate": "-----BEGIN CERTIFICATE-----CERTIFICATE_CONTENT-----END CERTIFICATE-----",
"certificateChain": "-----BEGIN CERTIFICATE-----CERTIFICATE_CHAIN_CONTENT-----END CERTIFICATE-----",
"expiresAt": "2024-09-15T12:10:00Z",
"activeFrom": "2024-03-15T12:10:00Z"
},
"rotationPeriod": {
"value": 6,
"interval": "MONTHS"
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
ID of the private CA. |
String |
|
Name of the CA. |
|
|
Current status of the CA. |
String |
|
Creation time of the CA. |
String |
|
Time at which the CA was last updated. |
String |
|
(Optional) Base64 PEM-encoded CSR for the CA. |
String |
|
(Optional) Details about the CA certificate. |
Object |
|
(Optional) CA certificate. |
String |
|
(Optional) Certificate chain imported to the CA. |
String |
|
Time after which the certificate of the CA isn't valid. Also known as expiration time of CA. |
String |
|
Time before which the certificate of the certificate authority isn't valid. |
String |
|
Specifies how often to rotate certificates on endpoints. |
Object |
|
Defines the rotation period. |
Integer |
|
Defines the rotation interval. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the details about the specified CA. |
|
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. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Import certificate
Import the signed CA certificate into the specified CA.
You must sign the CSR provided in the Get certificate authority details
operation on your RADIUS server. In return, your server provides you with the certificate and certificate chain to import to your CA.
After you import the certificate, Alexa marks your CA as ACTIVE
. This status enables the CA to issue certificates to ASP devices.
Request
To import the CA certification, you make a POST
request to the /v1/enterprise/certificateAuthorities/{certificateAuthorityId}/importCertificate
resource.
Request path and header example
POST /v1/enterprise/certificateAuthorities/{certificateAuthorityId}/importCertificate HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID of the private CA. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"certificate": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_CONTENT\nMULTIPLE_LINES_WITH_LINE_BREAK_CHARACTERS\n-----END CERTIFICATE-----",
"certificateChain": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_CONTENT\nMULTIPLE_LINES_WITH_LINE_BREAK_CHARACTERS\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n\nCERTIFICATE_CONTENT\nMULTIPLE_LINES_WITH_LINE_BREAK_CHARACTERS\n----END CERTIFICATE-----"
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
CA certificate to import. The certificate must be signed by your RADIUS server. |
String |
Yes |
|
All certificates in the chain to the root CA. |
String |
Yes |
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 object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
CA certificate imported successfully. |
|
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. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List certificate authorities
Get a list of all certificate authorities created by the caller. You can request to include details about each CA, including CA ID and status.
Request
To list the CAs, you make a GET
request to the /v1/enterprise/certificateAuthorities
resource.
Request path and header example
GET /v1/enterprise/certificateAuthorities?expand={expand}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Query |
Get expanded information about the certificate authority. |
String |
No |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. |
String |
No |
|
Header |
Access token for the customer. |
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 a list of CAs.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.
Response body example
{
"certificateAuthorities": [
{
"id": "amzn1.alexa.enterprise.certificateAuthority.did.1",
"friendlyName": {
"type": "PLAIN",
"value": {
"text": "Customer Network #1"
}
},
"status": "ACTIVE",
"createdAt": "2024-03-15T12:10:00Z",
"updatedAt": "2024-03-15T12:10:00Z",
"csr": "-----BEGIN CERTIFICATE REQUEST-----CERTIFICATE_REQUEST_CONTENT-----END CERTIFICATE REQUEST-----",
"certificateMetadata": {
"certificate": "-----BEGIN CERTIFICATE-----CERTIFICATE_CONTENT-----END CERTIFICATE-----",
"certificateChain": "-----BEGIN CERTIFICATE-----CERTIFICATE_CHAIN_CONTENT-----END CERTIFICATE-----",
"expiresAt": "2024-09-15T12:10:00Z",
"activeFrom": "2024-03-15T12:10:00Z"
},
"rotationPeriod": {
"value": 6,
"interval": "MONTHS"
}
}
],
"paginationContext": {
"nextToken": "someToken.1"
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
Array of |
Array |
|
ID of the private CA. |
String |
|
Name of the CA. |
|
|
Current status of the CA. |
String |
|
Creation time of the CA. |
String |
|
Time at which the CA was last updated. |
String |
|
(Optional) Base64 PEM-encoded string of the CSR for the CA. |
String |
|
(Optional) Details about the CA certificate. |
Object |
|
(Optional) CA certificate. |
String |
|
(Optional) Certificate chain imported to the CA. |
String |
|
Time after which the CA certificate isn't valid. Also known as expiration time of the CA. |
String |
|
Time before which the CA certificate isn't valid. |
String |
|
Specifies how often to rotate certificates on endpoints. |
Object |
|
Defines the rotation period. |
Integer |
|
Defines the rotation interval. |
String |
|
(Optional) Indicates whether there are more results to return. |
Object |
|
Included when the response is truncated. Use this value in a subsequent request. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of CAs. |
|
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. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update certificate authority
Update the specified CA. You can change the name of the CA or change the certificate rotation period.
Request
To update a CA, you make a PUT
request to the /v1/enterprise/certificateAuthorities/{certificateAuthorityId}
resource.
Request path and header example
PUT /v1/enterprise/certificateAuthorities/{certificateAuthorityId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID of the private CA to update. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"friendlyName": {
"type": "PLAIN",
"value": {
"text": "Customer Network #2"
}
},
"rotationPeriod": {
"value": 6,
"interval": "MONTHS"
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Name of the certificate authority. |
|
No |
|
Specifies how often to rotate certificates on endpoints. |
Object |
No |
|
Defines the rotation period. |
Integer |
Yes |
|
Defines the rotation interval. |
String |
Yes |
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 object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
CA updated successfully. |
|
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. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Certificate authority status
A CA can have one of the following statuses.
Status | Description | Can the CA issue certificates? | Can you get the CSR and install CA certificate? | Are you billed for the CA? |
---|---|---|---|---|
|
CA creation is in progress. |
No |
No |
Yes |
|
CA creation completed, but the CA needs a CA certificate to be operational. |
No |
Yes |
Yes |
|
CA is active and is ready to issue certificates. |
Yes |
Yes |
Yes |
|
CA certificate expired. |
No |
Yes |
Yes |
|
CA creation failed due to an internal error. You can't recover a failed CA. |
No |
No |
No |
Object definitions
The Certificate Authority Management API defines the following objects.
Error object
The Error
object defines the error type and message included in the response when an error occurs.
The following example shows the response body with the error type and message.
{
"type": "BAD_REQUEST",
"message": "The request is malformed or is missing any required parameters."
}
Property | Description | Type |
---|---|---|
|
Type of error that occurred. |
String |
|
The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.. |
String |
NameValue object
The NameValue
object is a container for names of objects.
The following table defines the properties of the object.
Property | Description | Type |
---|---|---|
|
Format of the value field. At this time, the only supported type is plain text. |
String |
|
Name. |
Object |
|
Name given in plain text. |
String |
Related topics
Last updated: frontmatter-missing