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:

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.

---

Device Secret properties

Property nameTypePIIDescription

device_sidSID<UV>

Not PII

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

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

---

keystring

Not PII

The secret key; up to 100 characters.

---

date_rotatedstring<date-time>

Not PII

---

urlstring<uri>

Not PII

The absolute URL of the Secret.

---

Create a Device Secret

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

Path parameters

Property nameTypeRequiredPIIDescription

DeviceSidstringrequired

Not PII

A 34-character string that uniquely identifies the Device.

Request body parameters

Property nameTypeRequiredPIIDescription

Keystringrequired

Not PII

The secret key; up to 100 characters.

---

Valuestringrequired

Not PII

The secret value; up to 4096 characters.

Create a Device Secret

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl

_21

// Download the helper library from https://www.twilio.com/docs/node/install

_21

const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

_21

_21

// Find your Account SID and Auth Token at twilio.com/console

_21

// and set the environment variables. See http://twil.io/secure

_21

const accountSid = process.env.TWILIO_ACCOUNT_SID;

_21

const authToken = process.env.TWILIO_AUTH_TOKEN;

_21

const client = twilio(accountSid, authToken);

_21

_21

async function createDeviceSecret() {

_21

const deviceSecret = await client.microvisor.v1

_21

.devices("UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

_21

.deviceSecrets.create({

_21

key: "Key",

_21

value: "Value",

_21

});

_21

_21

console.log(deviceSecret.deviceSid);

_21

}

_21

_21

createDeviceSecret();

Output

_10

{

_10

"device_sid": "UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

_10

"key": "Key",

_10

"date_rotated": "2021-01-01T12:34:56Z",

_10

"url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets/first"

_10

}

---

Read a single Device Secret's metadata

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

Path parameters

Property nameTypeRequiredPIIDescription

DeviceSidstringrequired

Not PII

A 34-character string that uniquely identifies the Device.

---

Keystringrequired

Not PII

The secret key; up to 100 characters.

Read a single Device Secret's metadata

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl

_19

// Download the helper library from https://www.twilio.com/docs/node/install

_19

const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

_19

_19

// Find your Account SID and Auth Token at twilio.com/console

_19

// and set the environment variables. See http://twil.io/secure

_19

const accountSid = process.env.TWILIO_ACCOUNT_SID;

_19

const authToken = process.env.TWILIO_AUTH_TOKEN;

_19

const client = twilio(accountSid, authToken);

_19

_19

async function fetchDeviceSecret() {

_19

const deviceSecret = await client.microvisor.v1

_19

.devices("UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

_19

.deviceSecrets("key_name")

_19

.fetch();

_19

_19

console.log(deviceSecret.deviceSid);

_19

}

_19

_19

fetchDeviceSecret();

Output

_10

{

_10

"device_sid": "UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

_10

"key": "key_name",

_10

"date_rotated": "2021-01-01T12:34:57Z",

_10

"url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets/first"

_10

}

---

List all of a Device's Secrets

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

Path parameters

Property nameTypeRequiredPIIDescription

DeviceSidstringrequired

Not PII

A 34-character string that uniquely identifies the Device.

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeintegerOptional

Not PII

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

Minimum: 1Maximum: 1000

---

PageintegerOptional

Not PII

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

Minimum: 0

---

PageTokenstringOptional

Not PII

The page token. This is provided by the API.

List all of a Device's Secrets

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl

_18

// Download the helper library from https://www.twilio.com/docs/node/install

_18

const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

_18

_18

// Find your Account SID and Auth Token at twilio.com/console

_18

// and set the environment variables. See http://twil.io/secure

_18

const accountSid = process.env.TWILIO_ACCOUNT_SID;

_18

const authToken = process.env.TWILIO_AUTH_TOKEN;

_18

const client = twilio(accountSid, authToken);

_18

_18

async function listDeviceSecret() {

_18

const deviceSecrets = await client.microvisor.v1

_18

.devices("UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

_18

.deviceSecrets.list({ limit: 20 });

_18

_18

deviceSecrets.forEach((d) => console.log(d.deviceSid));

_18

}

_18

_18

listDeviceSecret();

Output

_12

{

_12

"secrets": [],

_12

"meta": {

_12

"page": 0,

_12

"page_size": 50,

_12

"first_page_url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets?PageSize=50&Page=0",

_12

"previous_page_url": null,

_12

"url": "https://microvisor.twilio.com/v1/Devices/UVaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Secrets?PageSize=50&Page=0",

_12

"next_page_url": null,

_12

"key": "secrets"

_12

}

_12

}

---

Delete a Device Secret

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

Path parameters

Property nameTypeRequiredPIIDescription

DeviceSidstringrequired

Not PII

A 34-character string that uniquely identifies the Device.

---

Keystringrequired

Not PII

The secret key; up to 100 characters.

Delete a Device Secret

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl

_17

// Download the helper library from https://www.twilio.com/docs/node/install

_17

const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

_17

_17

// Find your Account SID and Auth Token at twilio.com/console

_17

// and set the environment variables. See http://twil.io/secure

_17

const accountSid = process.env.TWILIO_ACCOUNT_SID;

_17

const authToken = process.env.TWILIO_AUTH_TOKEN;

_17

const client = twilio(accountSid, authToken);

_17

_17

async function deleteDeviceSecret() {

_17

await client.microvisor.v1

_17

.devices("UVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

_17

.deviceSecrets("key_name")

_17

.remove();

_17

}

_17

_17

deleteDeviceSecret();