Skip to content Skip to navigation Skip to topbar

On this page

Secret Subresource

You can provide secret data for specific Microvisor-empowered IoT devices using the Secret subresource. Secrets are intended as a way to upload data such as PKI keys and other confidential items to the Twilio cloud so they need not be baked into application code. Instead, the application code running on the device retrieves the Secret when it needs the information.

Unlike Device Configs, Device Secrets' values cannot be accessed via the API once they have been created. The retrieval actions listed below will return Secrets' metadata, not their values.

Each Secret is a key:value pair which your application code can access using Microvisor System Calls.

Keys are text identifiers of up to 100 characters in length. They must be unique for a given device. For example, devices A and B can both have Secret with the key wifi_password, but each device can have only one Secret with that key.

Values must also be supplied as text, of up to 4096 characters in length. If you wish to make binary data available to your devices, you will need to encode it as text before creating the Secret. For example, you might used base64 encoding. Your application must decode the value back to binary after acquiring it from the Twilio cloud.

Secret subresources are accessed at these endpoints:

1https://microvisor.twilio.com/v1/Devices/{sid}/Secrets
2https://microvisor.twilio.com/v1/Devices/{UniqueName}/Secrets

Device Secrets are accessible only by the specified device. For Secrets that are made available to all devices associated with a given account, please see Account-level Secrets.

(warning)

Warning

Secrets can't yet be updated. If you need to change a Secret's value, delete it, and then create a new Secret with the same key.

Device Secret properties

Property nameTypeRequiredDescriptionChild properties

deviceSidSID<UV>

Optional

A 34-character string that uniquely identifies the parent Device.

Pattern: ^UV[0-9a-fA-F]{32}$Min length: 34Max length: 34

keystring

Optional

The secret key; up to 100 characters.

dateRotatedstring<date-time>

Optional

urlstring<uri>

Optional

The absolute URL of the Secret.

Create a Device Secret

POST https://microvisor.twilio.com/v1/Devices/{DeviceSid}/Secrets

Path parameters

Property nameTypeRequiredPIIDescription

deviceSidstring

required

A 34-character string that uniquely identifies the Device.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

keystring

required

The secret key; up to 100 characters.

valuestring

required

The secret value; up to 4096 characters.

Create a Device Secret

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createDeviceSecret() {
11  const deviceSecret = await client.microvisor.v1
12    .devices("UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
13    .deviceSecrets.create({
14      key: "Key",
15      value: "Value",
16    });
17
18  console.log(deviceSecret.deviceSid);
19}
20
21createDeviceSecret();

Response

1{
2  "device_sid": "UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3  "key": "Key",
4  "date_rotated": "2021-01-01T12:34:56Z",
5  "url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets/first"
6}

Read a single Device Secret's metadata

GET https://microvisor.twilio.com/v1/Devices/{DeviceSid}/Secrets/{Key}

Path parameters

Property nameTypeRequiredPIIDescription

deviceSidstring

required

A 34-character string that uniquely identifies the Device.

keystring

required

The secret key; up to 100 characters.

Read a single Device Secret's metadata

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchDeviceSecret() {
11  const deviceSecret = await client.microvisor.v1
12    .devices("UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
13    .deviceSecrets("key_name")
14    .fetch();
15
16  console.log(deviceSecret.deviceSid);
17}
18
19fetchDeviceSecret();

Response

1{
2  "device_sid": "UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
3  "key": "key_name",
4  "date_rotated": "2021-01-01T12:34:57Z",
5  "url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets/first"
6}

List all of a Device's Secrets

GET https://microvisor.twilio.com/v1/Devices/{DeviceSid}/Secrets

Path parameters

Property nameTypeRequiredPIIDescription

deviceSidstring

required

A 34-character string that uniquely identifies the Device.

Query parameters

Property nameTypeRequiredPIIDescription

pageSizeinteger<int64>

Optional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

pageinteger

Optional

The page index. This value is simply for client state.

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

List all of a Device's Secrets

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listDeviceSecret() {
11  const deviceSecrets = await client.microvisor.v1
12    .devices("UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
13    .deviceSecrets.list({ limit: 20 });
14
15  deviceSecrets.forEach((d) => console.log(d.deviceSid));
16}
17
18listDeviceSecret();

Response

1{
2  "secrets": [],
3  "meta": {
4    "page": 0,
5    "page_size": 50,
6    "first_page_url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets?PageSize=50&Page=0",
7    "previous_page_url": null,
8    "url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets?PageSize=50&Page=0",
9    "next_page_url": null,
10    "key": "secrets"
11  }
12}

Delete a Device Secret

DELETE https://microvisor.twilio.com/v1/Devices/{DeviceSid}/Secrets/{Key}

Path parameters

Property nameTypeRequiredPIIDescription

deviceSidstring

required

A 34-character string that uniquely identifies the Device.

keystring

required

The secret key; up to 100 characters.

Delete a Device Secret

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteDeviceSecret() {
11  await client.microvisor.v1
12    .devices("UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
13    .deviceSecrets("key_name")
14    .remove();
15}
16
17deleteDeviceSecret();