Endpoint Wi-Fi Management REST API Reference

Use the Endpoint Wi-Fi Management REST API to define Wi-Fi network configurations and assign them to an endpoint. In Alexa Smart Properties (ASP), an endpoint represents an Alexa-connected device or component with which an ASP resident can interact, such as Amazon Echo devices or Alexa-connected lights. Often property owners set up a device on a default Wi-Fi network, and then use these operations to assign additional Wi-Fi networks to a device. For Wi-Fi Protected Access 2 (WPA2) Enterprise Wi-Fi, you must associate the WPA2 Extensible Authentication Protocol (EAP) network with a device after device setup.

To assign Wi-Fi network configurations to an endpoint, invoke these operations in the following order:

  1. Save Wi-Fi configurations to the Amazon Wi-Fi locker for your account.
  2. Assign one or more of the saved Wi-Fi configurations to an endpoint.
    During this step, make sure that the endpoint is online.
  3. (Optional) Get the status of the configuration assignment.

You use the Endpoint Wi-Fi Management API along with the Endpoints REST API to view and change settings on devices owned by your Amazon Business account.

API endpoints

Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.

Country Endpoint

CA, US

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

JP

https://api.fe.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.

To use the Endpoint Wi-Fi Management API, request your LWA token with the following scopes:

  • credential_locker::wifi_management
  • alexa::enterprise:management

Operations

The Endpoint Features API includes the following operations.

Operation HTTP method and URI

Forget Wi-Fi configuration

POST /v2/endpoints/{endpointId}/features/connectivity/forgetWifiConfigurations

Get Wi-Fi installation status

GET /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId}

List Wi-Fi configurations

GET /v2/endpoints/{endpointId}/features/connectivity/wifiConfigurations

Save Wi-Fi configurations

POST /credentiallocker/v2/saveWifiConfigurations

Set Wi-Fi configuration

POST /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations

Forget Wi-Fi configuration

Delete the Wi-Fi configuration from the specified endpoint. To forget a Wi-Fi configuration, the device must be online and have at least two Wi-Fi network configurations assigned to the endpoint. If there is one Wi-Fi configuration associated with the an endpoint, you can't delete the specified Wi-Fi configuration from the endpoint.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

None

US, CA, UK, DE, FR, IT, ES, JP

US, CA, UK, DE, FR, IT, ES, JP

None

Request

To delete a configuration, you make a POST request to the /v2/endpoints/{endpointId}/features/connectivity/forgetWifiConfigurations resource.

Request path and header example

Copied to clipboard.

POST /v2/endpoints/{endpointId}/features/connectivity/forgetWifiConfigurations
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

endpointId

Path

Unique ID for this endpoint that Amazon assigns to each customer device.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.endpoint.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "payload": {
        "wifiConfigurations": [{
            "ssid": "wifi-name.1",
            "keyManagement": "WPAPSK"
        }]
    }
}

Request body properties

Property Description Type Required

payload

Contains the Wi-Fi configurations to delete.

Object

Yes

payload.wifiConfigurations

List of Wi-Fi configurations.
Include one configuration to delete.

Array of objects

Yes

payload.wifiConfigurations[].ssid

Wi-Fi network name.

String

Yes

payload.wifiConfigurations[].keyManagement

Wi-Fi configuration security type.
Valid values:

  • WPAPSK – Wi-Fi Protected Access (WPA2) with a pre-shared key.
  • WPA2_EAP – WPA2 Extensible Authentication Protocol (EAP).
  • OPEN – A Wi-Fi network that doesn't use any security.

String

Yes

Response

A successful response returns HTTP 200 OK. 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

200 OK

Specified Wi-Fi configuration deleted from the device successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

The response might include one of the following errors types and messages:

  • ALTERNATE_NETWORK_CONNECTION_FAILURE – The endpoint is connected to the specified Wi-Fi configuration and alternate configurations that exist on the device failed to connect.
  • BAD_REQUEST – Bad Request.
  • ENDPOINT_NOT_SUPPORTED – Endpoint not supported.
  • NO_ALTERNATE_NETWORK – The endpoint is connected to the specified Wi-Fi configuration and there is no alternate network configuration on the device.
  • TOO_MANY_CONFIGURATIONS – Request must contain exactly one Wi-Fi configuration.

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.

The response might include one of the following errors types and messages:

  • NO_SUCH_ENDPOINT – Endpoint not found.

429 Too Many Requests

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

500 Server Error

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

504 Gateway Timeout

No response from the endpoint.

The response might include one of the following errors types and messages:

  • ENDPOINT_UNREACHABLE – The endpoint is offline or unreachable.

Get Wi-Fi installation status

Get the status of a previous Set Wi-Fi configuration operation on the specified endpoint.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, CA, UK, DE, FR, IT, ES, JP

US, CA, UK, DE, FR, IT, ES, JP

US

Request

To get the status, you make a GET request to the /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId}
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

endpointId

Path

Unique ID for this endpoint that Amazon assigns to each customer device.
Formatted as an ACI, amzn1.alexa.endpoint.{id}.

String

Yes

operationId

Path

Unique submittedOperationId returned by the Set Wi-Fi configuration operation.

String

Yes

access token

Header

Access token for the customer.
Set to an 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 the status of the Wi-Fi configuration installation. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
    "status": {
        "value": "IN_PROGRESS"
    }
}

Response body properties

Property Description Type

status

Identifies the status of the requested Wi-Fi configuration installation for the specified endpoint.

Object

status.value

Operation status value.
Valid values: SUCCESS,FAILURE, TIMEOUT, IN_PROGRESS.

String

A TIMEOUT status for this operation indicates that the API attempted to install the network to the device, but the device didn't respond within five minutes. Try the following steps to fix the issue:

  1. Power-cycle the device.
  2. After the device starts up, wait for it to come fully online.
  3. Check the device networks with the List Wi-Fi configurations operation.
  4. If the the network wasn't installed, attempt to install again with Set Wi-Fi configuration.

HTTP status codes

Status Description

200 OK

Response body contains the current status of the Wi-Fi configuration installation.

300 Multiple Choices

The endpoint ID has changed, but the underlying resource is still the same. The response body contains a URI reference for the new endpoint ID, for example, /v2/endpoints/{newId}.

301 Moved Permanently

The endpoint ID has changed, but the underlying resource is still the same. The response body contains a URI reference for the new endpoint ID, for example, /v2/endpoints/{newId}.

303 See Other

The endpoint has been merged with another, causing the underlying resource to change. The response body contains a URI reference for the new endpoint ID, for example, /v2/endpoints/{newId}.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

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.

The response might include one of the following errors types and messages:

  • NO_SUCH_ENDPOINT – Endpoint not found.

429 Too Many Requests

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

500 Server Error

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

504 Gateway Timeout

No response from the endpoint.

The response might include one of the following errors types and messages:

  • ENDPOINT_UNREACHABLE – The endpoint is offline or unreachable.

List Wi-Fi configurations

Get the list of Wi-Fi configurations assigned to the specified endpoint. To list the Wi-Fi configurations, the device must be online.

Request

To list configurations, you make a GET request to the /v2/endpoints/{endpointId}/features/connectivity/wifiConfigurations resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/features/connectivity/wifiConfigurations
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

endpointId

Path

Unique ID for this endpoint that Amazon assigns to each customer device.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.endpoint.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an 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 a list of the Wi-Fi configurations. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
    "wifiConfigurations": [{
            "connectivityStatus": "CONNECTED",
            "keyManagement": "OPEN",
            "ssid": "wifi-name.1"
        },
        {
            "connectivityStatus": "NOT_CONNECTED",
            "keyManagement": "WPA2_PSK",
            "ssid": "wifi-name.2"
        }
    ]
}

Response body properties

Property Description Type

wifiConfigurations

List of Wi-Fi configurations saved to the endpoint.

Array of objects

wifiConfigurations[].connectivityStatus

Indicates the connection status of the endpoint to this Wi-Fi network.
Valid values: CONNECTED, NOT_CONNECTED.

String

wifiConfigurations[].keyManagement

Wi-Fi configuration security type.
Valid values:

  • WPAPSK – Wi-Fi Protected Access (WPA2) with a pre-shared key.
  • WPA2_EAP – WPA2 Extensible Authentication Protocol (EAP).
  • OPEN – A Wi-Fi network that doesn't use any security.

String

wifiConfigurations[].ssid

Wi-Fi network name.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of the Wi-Fi configurations associated with the specified endpoint.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

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.

The response might include one of the following errors types and messages:

  • NO_SUCH_ENDPOINT – Endpoint not found.

429 Too Many Requests

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

500 Server Error

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

504 Gateway Timeout

No response from the endpoint.

The response might include one of the following errors types and messages:

  • ENDPOINT_UNREACHABLE – The endpoint is offline or unreachable.

Save Wi-Fi configurations

Save Wi-Fi configurations to the Amazon Wi-Fi locker for your account. Later, you assign one or more of these configurations to endpoints with the Set Wi-Fi configuration operation. To use a network with a hidden Service Set Identifier (SSID), configure the network with the hidden SSID before you save the Wi-Fi configuration.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, CA, DE, ES, FR, IT, UK, JP

US, CA, DE, ES, FR, IT, UK, JP

US

Request

To save Wi-Fi configurations, you make a POST request to the /credentiallocker/v2/saveWifiConfigurations resource.

API endpoints

Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.

Country Endpoint

CA, US

https://credential-locker-service.amazon.com

DE, ES, FR, IT, UK

https://credential-locker-service.amazon.eu

JP

https://credential-locker-service.amazon.jp

Request path and header example

Copied to clipboard.

POST /credentiallocker/v2/saveWifiConfigurations
Host: credential-locker-service.amazon.com
x-amz-access-token: {access token}
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

The follow example shows a Wi-Fi configuration that uses Wi-Fi Protected Access 2 (WPA2) with a shared key (WPAPSK) for network access.

The follow example shows a Wi-Fi configuration that uses WPA2_EAP with certificates for enterprise network access.

Request body properties

Field Description Type Required

wifiConfigurations

List of Wi-Fi configurations to save.

Array of objects

Yes

wifiConfigurations[].ssid

Wi-Fi network name.
Enclose the name in double quotation marks as follows: "\"ssid\""

String

Yes

wifiConfigurations[].keyManagement

Wi-Fi configuration security type.
Valid values:

  • WPAPSK – Wi-Fi Protected Access (WPA2) with a pre-shared key.
  • WPA2_EAP – WPA2 Extensible Authentication Protocol (EAP).
  • OPEN – A Wi-Fi network that doesn't use any security.

String

Yes

wifiConfigurations[].credentialConfiguration

Credential information for the Wi-Fi network.

CredentialConfiguration object

Yes

Response

A successful response returns HTTP 200 OK. 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

200 OK

Wi-Fi configurations saved successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

The response might include one of the following errors types and messages:

  • CERTIFICATE_MISMATCH – The specified CA certificate doesn't comply with conditions specified in the certificate that signed it.

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.

The response might include one of the following errors types and messages:

  • NO_SUCH_ENDPOINT – Endpoint not found.

429 Too Many Requests

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

500 Server Error

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

504 Gateway Timeout

No response from the endpoint.

The response might include one of the following errors types and messages:

  • ENDPOINT_UNREACHABLE – The endpoint is offline or unreachable.

Set Wi-Fi configuration

Associate a saved Wi-Fi configuration with the specified endpoint. To save the Wi-Fi configuration to the device, the endpoint must be online. You can associate up to 32 Wi-Fi configurations with a single endpoint, one configuration at a time.

During normal operation, the endpoint tries to connect to one of the Wi-Fi networks assigned to the device. If a Wi-Fi network becomes unavailable, the device might go offline, but eventually connects to an available Wi-Fi network.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

None

US, CA, UK, DE, FR, IT, ES, JP

US, CA, UK, DE, FR, IT, ES, JP

None

Request

To set a Wi-Fi configuration, you make a POST request to the /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations resource.

Request path and header example

Copied to clipboard.

POST /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

endpointId

Path

Unique ID for this endpoint that Amazon assigns to each customer device.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.endpoint.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "payload": {
        "wifiConfigurations": [{
            "ssid": "\"wifi-name.1\"",
            "keyManagement": "WPAPSK"
        }]
    }
}

Request body properties

Field Description Type Required

payload

Contains the Wi-Fi configuration definition.

Object

Yes

payload.wifiConfigurations

List of Wi-Fi configurations to add or update on the specified endpoint.
Only include configurations defined with the Save Wi-Fi configuration operation.
Include up to one configuration in the array.
Maximum number of configurations per endpoint: 32.

Array of objects

Yes

payload.wifiConfigurations[].ssid

Wi-Fi network name.
Enclose the name in double quotation marks as follows: "\"ssid\""

String

Yes

payload.wifiConfigurations[].keyManagement

Wi-Fi configuration security type.
Valid values:

  • WPAPSK – Wi-Fi Protected Access (WPA2) with a pre-shared key.
  • WPA2_EAP – WPA2 Extensible Authentication Protocol (EAP).
  • OPEN – A Wi-Fi network that doesn't use any security.

String

Yes

Response

A successful response returns HTTP 200 OK, along with the identifier to use to get the status of the Wi-Fi configuration installation. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
    "submittedOperationId": "operationId.1"
}

Response body properties

Property Description Type

submittedOperationId

Identifies the request to set the configuration for the endpoint.
Use this value in Get Wi-Fi installation status.

String

HTTP status codes

Status Description

202 Accepted

Wi-Fi configurations added or updated on the specified endpoint successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

The response might include one of the following errors types and messages:

  • ENDPOINT_NOT_SUPPORTED – Adding or updating wifi configurations remotely is not supported for the specified endpoint.
  • INVALID_CA_CERTIFICATE – A certificate cannot be issued for this request as the certificate authority certificate will expire or has expired before the expiration time of the issued certificate.
  • INVALID_CA_STATUS – The certificate authority linked to this SSID is not in an ACTIVE state and can't issue a certificate for this request.
  • INVALID_CONFIGURATION – Request contains invalid WiFi configuration format.
  • TOO_MANY_CONFIGURATIONS – Request must contain exactly one Wi-Fi configuration.

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.

The response might include one of the following errors types and messages:

  • NO_SUCH_ENDPOINT – Endpoint not found.

429 Too Many Requests

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

500 Server Error

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

504 Gateway Timeout

No response from the endpoint.

The response might include one of the following errors types and messages:

  • ENDPOINT_UNREACHABLE – The endpoint is offline or unreachable.

Object definitions

The Endpoint Wi-Fi Management API defines the following objects.

CertificateAuthority object

The CertificateAuthority object identifies the certificate authority organization that creates and verifies digital certificates.

Property Description Type

providerName

Identifies the certificate authority organization.

String

id

Identifies the certificate authority resource within the provider system.

String

CredentialConfiguration object

The CredentialConfiguration object defines the configuration of a Wi-Fi network.

Property Description Type

privateSharedKey

(Optional) Password for Wi-Fi network access, enclosed in double quotation marks. Required for WPAPSK key management. Set to "null" for OPEN networks.

String

eapAuthenticationMethod

(Optional) Identifies the Extensible Authentication Protocol (EAP) for Wi-Fi network access. Required for WPA2_EAP key management.
Valid values: EAP-TLS.

String

certificateAuthority

(Optional) Identifies the certificate authority.
Required for WPA2_EAP key management.

CertificateAuthority object

authenticationServerCertificates

(Optional) List of certificates used to identify a trusted network.
Required for WPA2_EAP key management.

Array of strings

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 code and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
Property Description Type

type

Type of error that occurred.
For specific error types, see the HTTP status code table for each operation.

String

message

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

Was this page helpful?

Last updated: Dec 12, 2024