Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

IoT Security Primer

Sync for IoT is currently in Developer Preview, which means access is by invite only. If you'd like to try what you see in these docs, sign up for the developer preview and the team at Twilio will get you onboarded.

Management of your Internet of Things devices in the Twilio Cloud begins with the IoT Device Manager, a tool available in your console. The Device Manager (DM) is the place where the credentials your devices use — including custom certificates, deviceId-password pairs, and (soon) Twilio Wireless on-SIM certificates — are paired with configuration for those devices. From there, devices can be enabled, they can be blacklisted, and they can be selectively granted access to the full extent of the Twilio Runtime and the Cloud Communications suite.


As for all Twilio services, security is paramount. This goes double for IoT devices, so the primary function of the IoT Device Manager is to authenticate your devices and let you control access to Twilio resources. We do this using per-device credentials, either auto-generated username/password keys, developer-provided certificates, or trusted credentials from your Twilio Wireless SIM cards.

In any case, every device must have at least one unique credential in the Device Manager for that device to connect. The easiest and most secure credentials are built-in X.509 certificates from your Wireless SIM cards, which Twilio will authenticate and apportion automatically according to your devices. These certificates can be rotated out-of-band via Twilio's SIM Management tool, making them especially secure. Twilio can also authenticate third-party certificates, or for quick development without a Twilio SIM you can generate username/password pairs from the Console.

Background: Why should IoT devices authenticate differently?

Devices in the Internet of Things, are distinguished from more traditional devices (e.g. laptops, cell phones, tablets) in two critical ways. First, they are often deployed, operating day-to-day at a great distance from the developer, the operator, or even the end-user. Storing and manipulating credentials on such devices is more difficult to do securely. Second, IoT devices tend to be "humanless", meaning no human is present who can be challenged to enter a password from memory. How do we ask a device to authenticate itself, i.e. prove that it is who it claims to be?

So the more common authentication primitives that Twilio provides — HTTP basic authentication for servers, and FPA tokens for browser and mobile SDKs — are not the right fit for the IoT space. To use the former, you would have to deploy your Auth Token or API Key on the device itself, giving that device complete, unfettered access to the Twilio REST API. FPA tokens are better, but the challenge of prompting devices to authenticate with your own backend remains.

To secure your devices, Twilio recommends per-device credentials, ideally X.509 certificates.

Per-Device Credentials

To ensure reasonable security and minimal re-use of credentials, the Twilio Runtime enforces a rule: each credential, whether certificate or username/password pair, identifies at most one device at a time. This way, much like with FPA tokens, when a device connects to the Runtime Twilio can tell from the credentials alone:

  • whether the device is authorised,
  • to which account the device belongs, and
  • to which Twilio services (via Fleets and Deployments) the device belongs.

Per-device credentials in the Twilio Console can be revoked and/or rotated. The devices themselves can enabled or blacklisted, and via the deployment they be assigned to different Twilio services. All of this can be done via the REST API in addition to via the Console, giving you full control over your customer experience.

Certificates vs. DeviceId/Password

X.509 Certificates are the preferred mechanism for authentication in Twilio. These work with both MQTTS connections and Twilio secure websockets (coming soon), and do not require secrets to be transmitted in cleartext. As your work comes together and you’re considering a move to production, we strongly encourage you to involve certificate authentication in your work.

For getting up and running during development, MQTT connections can also be authenticated with a username/password combination. The username is always the key SID and password is the key secret; you may have any number of keys to match each device.

Managing Credentials

Credentials of all kinds can be provisioned either via the REST API or via the Console. In either case, Credentials are grouped under their corresponding Device; although credentials can be repurposed and reassigned from one device to another, two devices may never share the same credential. Two certificates are considered duplicates if they share a common thumbprint. Among username/password pairs, the username (i.e. Key SID) determines uniqueness.

Provisioning a new Certificate in the Console

Log into Twilio developer Console and navigate to Device Manager > Fleets > Devices.

  • Pick a device that you want to register a certificate for, then click on it to get to "Configure Device" page.
  • Click on "Certificates" in the context menu on the left.
  • Click the "Create a Certificate" button.
  • Check the "Generate" box to have the certificate helper tool generate a new certificate and a private key for you. Note: Twilio does not store your private key in any way, and it is returned as part of transient website content.
  • Leave the Device SID unchanged, it points to your selected device already.
  • Click the "Create" button, your new certificate is now registered, with some additional artifacts displayed on the next page.

The private key is made available only once after its creation, make sure you fetch it. The resulting generated certificate is self-signed and valid for one year. Click "Certificate download" to download the generated certificate in PEM format (the name of the file will match the certificate SID). Click "Private Key download" to download the private key in PEM format to be used with above certificate, and provision to your device securely. Note the passphrase that is used to decrypt the private key.

For more details on using the IoT Device Manager, please refer to to Adding Credentials guidelines.

Provisioning a new Certificate via the REST API

We recommend to use Elliptic Curve cryptography to reduce the key and certificate footprints and minimize the resulting mutual TLS handshake traffic. The following algorithms provide sufficiently strong security while keeping the handshake lightweight:

  • ECC key pair using NIST P-256 curve (prime256v1)
  • SHA256 signature

Please also pay attention to the device certificate expiration date. Once the certificate expires, Twilio gateways will not accept it anymore to establish connectivity, and it must be rotated out-of-band.

You can generate your device private key and certificate using OpenSSL like illustrated below:

openssl ecparam -genkey -name prime256v1 -out device-key.pem
openssl req -new -x509 -sha256 -days 365 -key device-key.pem -out device-cert.pem

After your certificate and private key are generated, enroll the public part it with IoT Device Manager REST API, associating with your device by SID. Make sure that private key is never exposed, and securely persisted in your device storage.


        For more details on using the REST API, please refer to to the REST API Documentation.

        Rotating a Credential

        Broadly speaking, rotation is accomplished the following way:

        1. Provision a new credential, attaching it to the Device alongside any existing credentials.
        2. Deploy the private component of the credential to the device and force a reconnection.
        3. Remove or disable the old credential.

        Deploying the credential to the device is the most difficult thing to do securely. With the upcoming Wireless on-SIM X.509 certificates, Twilio will provide the facilities to rotate this credential out-of-band using our carrier network. In all other cases, avoid transmitting the certificate via e-mail or the public internet.

        Rate this page:

        Need some help?

        We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.