Monitoring Updates to Twilio REST API Security Settings

At Twilio, we believe in security, operational excellence, and transparency to build trust between us and our customers. To this end, we are publishing our REST API security update procedures to enable customers to monitor for any upcoming changes to certificates, TLS versions or cipher suites. This document is meant to be a “How To” guide to monitor for these changes.

REST API Security Upgrade Procedures

At least one month in advance of any REST API security change, we will post the new "to be upgraded" certificate and configuration on port 8443 of all of our REST API endpoints. These include but are not exclusive to:

  • api.twilio.com
  • lookups.twilio.com
  • notify.twilio.com
  • partners.twilio.com
  • preview.twilio.com
  • taskrouter.twilio.com

How to Monitor for Changes

Customers can monitor for any upcoming security change with a simple script to check port 8443 of our REST API. If the request succeeds with 200 OK, no further action is required. If there is a timeout or error message, further investigation is required to determine the cause and resolve any issues. Code snippets for connecting to port 8443 are available in the next section.

Testing Your Environment

The best way to test if your environment is impacted by a TLS or certificate change is by sending an HTTP request to our test endpoint on port 8443 (i.e. https://api.twilio.com:8443) from your production environment (or one that is identical to production). If your HTTP request succeeds, no changes will be needed on your end for the update.

Note: Be sure your environment allows outbound HTTPS traffic to port 8443.

Expected Results

If the test succeeds, you'll receive a 200 OK status code and XML or JSON output similar to this content body:

<?xml version='1.0' encoding='UTF-8'?>
<TwilioResponse>
  <Versions firstpageuri="/?Page=0&amp;PageSize=50" numpages="1" end="1" total="2" previouspageuri="" lastpageuri="/?Page=0&amp;PageSize=50" uri="/" pagesize="50" start="0" nextpageuri="" page="0">
    <Version><Name>2008-08-01</Name><Uri>/2008-08-01</Uri><SubresourceUris><Accounts>/2008-08-01/Accounts</Accounts></SubresourceUris></Version>
    <Version><Name>2010-04-01</Name><Uri>/2010-04-01</Uri><SubresourceUris><Accounts>/2010-04-01/Accounts</Accounts></SubresourceUris></Version>
  </Versions>
</TwilioResponse>

If your command fails, then outside of syntax errors, your local trust store may be missing our root certificate or your system does not support the TLS version or cipher suites enabled on the test endpoint.

Note: We do not recommend pinning certificates, but if you or your organization are pinning root certificates, please ensure the DigiCert Global Root CA is available in your local trust store.

Testing with cURL

The simplest method to test is to run this command via cURL from your production server:

curl https://api.twilio.com:8443 --tlsv1.2

Testing with Twilio Helper Libraries

If you are using one of Twilio's new Helper Libraries, you can test with the code snippets listed below.

Note: For Twilio's legacy Helper Libraries such as C# 3.x, download these snippets separately.

C# (.NET 4+)

The following snippet is for helper library version >= 5.x. (Download older library version snippets.)

using System;
using Twilio.Http;

class TwilioApiTest
{
    static void Main(string[] args)
    {
            HttpClient client = new SystemNetHttpClient();
            Request request = new Request(HttpMethod.Get, "https://api.twilio.com:8443");
            Response response = client.MakeRequest(request);
            Console.Write(response.Content);
    }
}

C# (.NET 3.5)

The following snippet is for helper library version >= 5.x. (Download older library version snippets.)

using System;
using Twilio.Http;
using Twilio.Http.Net35;

class TwilioApiTest
{
    static void Main(string[] args)
    {
            HttpClient client = new WebRequestClient();
            Request request = new Request(HttpMethod.Get, "https://api.twilio.com:8443");
            Response response = client.MakeRequest(request);
            Console.Write(response.Content);
    }
}

Java

The following snippet is for helper library version >= 7.x. (Download older library version snippets.)

import com.twilio.http.*;

public class TwilioApiTest {
    
    public static void main(String[] args) {
        NetworkHttpClient client = new NetworkHttpClient();
        Request request = new Request(HttpMethod.GET, "https://api.twilio.com:8443");
        Response response = client.makeRequest(request);
        System.out.print(response.getContent());
    }
}

Node.js

The following snippet is for helper library version >= 3.x. (Download older library version snippets.)

var RequestClient = require('twilio/lib/base/RequestClient');

var client = new RequestClient();
client.request({
    method: 'GET',
    uri: 'https://api.twilio.com:8443'
}).
then(function(response){
  console.log(response.body);
});

PHP

The following snippet is for helper library version >= 5.x. (Download older library version snippets.)

<?php
require __DIR__ . '/vendor/autoload.php'; $client = new Twilio\Http\CurlClient(); $response = $client->request('GET', 'https://api.twilio.com:8443'); echo $response;

Python

The following snippet is for helper library version >= 3.x. (Download older library version snippets.)

from twilio.http.http_client import TwilioHttpClient

client = TwilioHttpClient()
response = client.request('GET', 'https://api.twilio.com:8443')
print(response)

Ruby

The following snippet is for helper library version >= 5.x. (Download older library version snippets.)

require 'twilio-ruby'

@client = Twilio::REST::Client.new
response = @client.request('api.twilio.com', '8443', 'GET', 'https://api.twilio.com:8443/.json')
puts response

Notifications

For routine updates to refresh expiring certificates, we will not send out any customer notification. However, if our security change affects the encryption level, encryption cipher, root chain or root certificate in any way, we will send out notification via email with at least one month’s notice. This procedure will be followed on any type of update to our REST API security configuration.

We hope this stated policy will help our customers stay operationally excellent and increase your trust in Twilio.

If you have any questions, please contact Customer Support.

Have more questions? Submit a request
Powered by Zendesk