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?

Connecting to Twilio's MQTT Gateway

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 as soon as possible.

Twilio supports MQTT connectivity with TLS security. Your clients need to be configured to establish MQTT/S connections with one of the following datacenters. We support MQTT Protocol version 3.1.1.

Datacenter Hostname Port URL
US East 8883 mqtts://

The Clean Session flag allows a device to start its session from scratch (Clean Session = 1). The alternative is to resume the previous session, reusing all topic subscriptions and receiving any pending updates. Of these two options, we generally recommend the latter, as it will best take advantage of Sync's state synchronization properties.

As of today, MQTT Gateway does not support the Last Will and Testament for MQTT sessions.

Also as of today, MQTT Gateway supports two client authentication methods as follows.

  • Certificate authentication i.e. mutual TLS (mTLS), in which the client sends its own validated certificate while establishing connection.
  • Device-specific Key/Secret authentication, where client supplies credentials via MQTT protocol username/password pair.

For both of these methods, a device is identified by the provided credential, and device specific attributes (such as SID and identity) are propagated through the Twilio service stack for reference and authorization purposes.

Note: In order to manage the device state reliably, we allow only one established connection with the given device SID at any time. In case the credential is reused, or same device connects with a different credential, the MQTT Gateway forcefully disconnects the old client.

Today, MQTT Gateway supports the following TLS cipher suites (listed with decreasing preference). We do not support plaintext MQTT, in order to mitigate security threats to your application.


Connecting with a Certificate

In this authentication mode, MQTT client running on your device presents its own X.509 certificate while performing an mTLS handshake with MQTT Gateway. This certificate can be signed by any CA, or even self-signed. Twilio infrastructure will not discriminate among these, as the trust is established through private/public key challenge and not the PKI signature based chain of trust. We recommend using ECC cryptography to reduce key and certificate footprint and minimize resulting mTLS handshake traffic. The following algorithms provide both strong security while keeping the handshake lightweight: ECC key pair using NIST P-256 curve (prime256v1) and SHA256 signature.

Certificate authentication is generally preferred, as it is more secure, since the private key never leaves a secure environment.

Note: When a client certificate is provided, the MQTT Gateway will ignore Client ID, User Name and Password fields of the CONNECT message.

  • Refer to Adding Credentials Console documentation for more information on generating certificates via IoT Device Manager.
  • Refer to Certificates REST API documentation for more details on submitting certificates programmatically.
  • Finally, consult the IoT Security Primer for best practices on device authentication.

Connecting with a Device Key

In this authentication mode, MQTT client running on your device must send a standard protocol CONNECT message containing the following fields. TLS handshake must not include a client certificate with this authentication method.

  • Client ID: can be anything, used as device metainfo; this has no functional impact.
  • User Name: provide a valid Device Key SID (KYxx), generated by IoT Device Manager or REST API.
  • Password: provide the matching Key Secret, generated with the Key above.

Device Key authentication might appear easier for development and testing purposes, but inherently has weaker secutity, as the key must be copied to the device and can be compromised on the way. Therefore, take measures to store keys in a secured fashion.

  • Refer to Adding Credentials Console documentation for more information on generating keys via IoT Device Manager.
  • Refer to Keys REST API documentation for more details on enrolling the device keys programmatically.
  • Finally, consult the IoT Security Primer for best practices on device authentication.

Validating the Server Certificate

Your device deployed to a production environment should always validate the certificate of a server it connects to. In a typical scenario, the MQTT client running on your device will automatically validate the MQTT Gateway certificate against a known-good list of root Certificate Authorities (CAs) supplied by the OS (e.g. MQTT.js, Paho). For other MQTT clients, you will need to specify the location of root CAs manually (e.g. embedded systems). Twilio Sync for IoT uses the following root CAs:

As part of the standard certificate validation procedure, your client must check the root CA validity, certificate chain validity and match the Common Name attribute of the leaf (server) certificate to the server hostname.

Error Codes

In some cases, MQTT Gateway may close the connection and return a standard error code. The error code may be retrieved from CONNACK message field "Connect Return Code". Please refer to the table below to map error codes to possible root causes, for troubleshooting purposes.

Connect Return Code Description Possible Reasons
0 Connection Accepted No error, connection established successfully.
1 Connection Refused, unacceptable protocol version Gateway supports CONNECT requests with protocol attribute "MQTT" and version "3.1" or "3.1.1". Device should retry with correct protocol.
2 Connection Refused, identifier rejected Supplied credentials are malformed. Device should retry with correct credentials (certificate or key).
3 Connection Refused, server unavailable Connection attempts are rate limited, or gateway service is temporarily unavailable. Device should try again later.
4 Connection Refused, bad user name or password Device authentication failed: no such device is registered with Twilio. Device should not retry with given credentials anymore.
5 Connection Refused, not authorized Device is not allowed to connect: the device is either disabled or not deployed to use any service. Device should not retry until the device is fully provisioned.
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.