Credential Locker REST API Reference

Use the Credential Locker REST API in your smart home skill to view customer Thread network credentials or create a new customer Thread network for Matter device setup.

You can use these credentials to commission Matter devices to the customer's Thread network, known as a wireless Personal Area Network (PAN). Here, the customer's Amazon Echo acts as a Thread border router. When a customer enables your smart home skill, they can share their network credentials with Alexa and your skill, eliminating the step to enter network credentials manually. For more details about Thread, see The Thread group.

For Wi-Fi networks, you can commission your Matter devices by using the Alexa.Commissionable interface.

API endpoint

The endpoint of the Credential Locker API is https://credential-locker-service.amazon.com.

Authentication

Each API request must have an authorization header whose value is the access token that your skill uses to send events to the Alexa event gateway. For details, see Send Events to the Alexa Event Gateway.

Access to credentials requires that you enable the permission scope for your skill. For details, see Add permissions for Thread network credentials.

Operations

The Credential Locker API includes the following operations.

Operation HTTP method and URI

Create Thread network

PUT /credentiallocker/v2/threadNetworks

Get Thread networks

GET /credentiallocker/v2/threadNetworks?extendedPanId={extendedPanId}&networkName={networkName}&maxResults={maxResults}&nextToken={nextToken}

Create Thread network

Create a new customer Thread network. Use this API if you don't find any available networks after you scan for Thread networks to join.

Request

To create a Thread network, you make a PUT request to the credentiallocker/v2/threadNetworks resource.

Request path and header example

Copied to clipboard.

PUT /credentiallocker/v2/threadNetworks
Host: credential-locker-service.amazon.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request body example

{
    "threadNetwork": {
        "extendedPanId": "extended.pan.id.1",
        "networkName": "MyThreadNetwork",
        "networkKey": "network.key.1"
    }
}

Request body properties

Property Description Type Required

threadNetworks

Thread network to create.

Object

Yes

threadNetworks.extendedPanId

Extended PAN ID of the Thread network.
Valid values: UTF-8 encoded 8-byte hex string.

String

Yes

threadNetworks.networkName

Human-readable name for the Thread network.

String

Yes

threadNetworks.networkKey

16-byte key used to access the network.
Valid values: UTF-8 encoded 16-byte hex string.

String

Yes

threadNetworks[].pskc

Commissioning key that enables devices to join the Thread network.
Valid values: UTF-8 encoded 16-byte hex string.

String

No

threadNetworks[].panId

2-byte personal area network ID.

String

No

threadNetworks[].channelNumber

802.15.4 radio channel that the Thread network uses.
Valid values: 11–26.

Integer

No

threadNetworks[].defaultBorderAgentId

Unique identifier for a Thread border agent, such as the Echo.
Valid values: UTF-8 encoded 16-byte hex string.

String

No

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

Thread network created successfully.

422 Unprocessable Content

Thread network already exists.

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.

Get Thread networks

Get the customer Thread networks that match the specified filter criteria.

Request

To get the Thread networks, you make a GET request to the credentiallocker/v2/threadNetworks resource.

Request path and header example

Copied to clipboard.

GET /credentiallocker/v2/threadNetworks?extendedPanId={extendedPanId}&networkName={networkName}&maxResults={maxResults}&nextToken={nextToken}
Host: credential-locker-service.amazon.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

extendedPanId

Query

Extended PAN ID of the Thread network. You find this ID during service discovery, such as DNS-SD.
Valid values: UTF-8 encoded 8-byte hex string.

String

Yes

networkName

Query

Human-readable name for the Thread network..

String

No

maxResults

Query

Maximum number of results to return in the response.
Default value: 100.

Integer

No

nextToken

Query

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

String

No

access token

Header

Alexa event gateway access 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. 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

{
    "threadNetworks": [{
        "extendedPanId": "extended.pan.id.1",
        "networkName": "myThreadNetwork",
        "networkKey": "network.key.1",
        "pskc": "pskc.1",
        "panId": "pan.id",
        "channelNumber": 16,
        "defaultBorderAgentId": "border.agent.id"
    }],
    "nextToken": "someToken.1"
}

Response body properties

Property Description Type

threadNetworks

List of Thread networks that match the filter criteria.

Array of objects

threadNetworks[].extendedPanId

Extended PAN ID of the Thread network.
Valid values: UTF-8 encoded 8-byte hex string.

String

threadNetworks[].networkName

Human-readable name for the Thread network. Maximum size: 16 bytes.

String

threadNetworks[].networkKey

16-byte key used to encrypt and decrypt traffic in the network.
Valid values: UTF-8 encoded 16-byte hex string.

String

threadNetworks[].pskc

Commissioning key that enables devices to join the Thread network.
Valid values: UTF-8 encoded 16-byte hex string.

String

threadNetworks[].panId

(Optional) 2-byte personal area network ID.

String

threadNetworks[].channelNumber

(Optional) 802.15.4 radio channel that the Thread network uses.
Valid values: 11–26.

Integer

threadNetworks[].defaultBorderAgentId

(Optional) Unique identifier for a Thread border agent, such as the Echo.
Valid values: UTF-8 encoded 16-byte hex string.

String

nextToken

Identifies the next set of results to return. The token expires in 24 hours.
Use this value for the nextToken parameter in a subsequent Get Thread networks request.
When there are no more matching results, nextToken isn't included in the response.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of Thread networks known to Alexa.

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: Sep 24, 2024