Credential Locker REST API Reference

Use the Credential Locker REST API in your smart home add-on 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 add-on, they can share their network credentials with Alexa and your add-on, 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 add-on 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 add-on. 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

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

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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Credential Locker REST API Reference

API endpoint

Authentication

Operations

Create Thread network

Request

Request path and header example

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Get Thread networks

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

​API endpoint

​Authentication

​Operations

​Create Thread network

​Request

​Request path and header example

​Request body example

​Request body properties

​Response

​Response body example

​Response body properties

​HTTP status codes

​Get Thread networks

​Request

​Request path and header example

​Request path and header parameters

​Request body example

​Request body properties

​Response

​Response body example

​Response body properties

​HTTP status codes

​Related topics

API endpoint

Authentication

Operations

Create Thread network

Request

Request path and header example

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Get Thread networks

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Related topics