Rate this page:

Public Key Client Validation Quickstart

This guide will walk you through the steps of implementing Public Key Client Validation. We include sample cURL commands and HTTP requests, then at the end we'll detail the steps in Java.

Public key client validation quickstart

To get started quickly, you can follow the Java example at the bottom of the page. It shows how Client Validation can be implemented, along with links to the Twilio Java helper library that supports this feature.

Steps to send a Request

  1. Generate an RSA Key Pair: Create a valid key pair. (This only has to be done once.)
  2. Submit the Public Key: Submit the public key to the Twilio via the Credentials Endpoint. (This is a one time requirement as well.)
  3. Hash the Canonical Request: Every outgoing request needs to be hashed and signed. (This functionality is implemented in the Java helper library and can be seen below.)
  4. Generate JWT: Once the hash is created, it needs to be embedded in the JWT payload and signed with the private key. (This is also handled by the Java helper library.)
  5. Attach JWT to the request header: The last step is to add the JWT to the request header.

1. Generate an RSA Keypair

A private key is used to sign your requests. It is is verified by the public key which you provide to Twilio.

Note: When you generate the private key, be sure to save and protect it as this is the only means to verify your application's identity.

We recommend generating the RSA key pair using the OpenSSL toolkit.

For Windows Systems

Install and use Cygwin to run the OpenSSL RSA keypair commands below.

For Mac and Linux/Unix-based Systems

You can run the OpenSSL commands to generate an RSA Keypair.

Generate a Private Key

openssl genrsa -aes256 -out private_key.pem 2048

Note: Twilio will only accept keys which have a bit length of 2048 with an exponent of 65537.

Generating a Public Key

openssl rsa -pubout -in private_key.pem -out public_key.pem

Example Public Key Format If properly generated, the RSA public key should look like the example public key below:

-----END PUBLIC KEY-----

Be sure to include the full header and footer when submitting the key: * '-----BEGIN PUBLIC KEY-----' AND * '-----END PUBLIC KEY-----'

You can see your Public Key with this command:

cat public_key.pem

2. Submit the Public Key to Twilio

Sample Requests cURL

curl -X POST "" \
-H "Authorization: Basic <token>" \
-F "PublicKey=-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BA....9xQIDAQAB-----END PUBLIC KEY-----" \
-F "FriendlyName=Client Validation" 

Note: Line breaks in the PEM format of the key need to be removed when making the cURL request.

Sample Response

  "date_updated": "2016-10-25T19:54:49Z", 
  "friendly_name": "Client Validation",
  "account_sid": "AC171b8eb......e737e0ee2cb99ee",
  "url": "",
  "sid": "CR934061....ed833471f596a5b4", 
  "date_created": "2016-10-25T19:54:49Z"

3. Hash the Canonical Request

The following section describes how the request needs to be canonicalized, hashed and attached to the request.

_Note: The Java helper library implements this functionality and will do the work for you. An end-to-end example is on the bottom of this page. _

This approach is loosely based on the approach Amazon is using to sign AWS API requests.

Canonical request pseudocode

Canonical HTTP Method + '\n' +
  Canonical URI + '\n' +
  Canonical Query String + '\n' +
  Canonical Headers + '\n' +
  Signed Headers + '\n' +
  HexEncode(Hash(Request Body))

Hashing Example

Example HTTP Request

POST /2010-04-01/Accounts/AC00000000000000000000000000000000
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 33

FriendlyName=my new friendly name

Canonicalize the HTTP Method

The HTTP method is canonicalized by doing the following operations:

  1. Uppercase
  2. Trim

In the Example Request, this results in:


Canonicalize the Resource Path

To canonicalize the resource path:

  1. Remove redundant path elements, for example:
    • '/foobar/./barfoo' becomes '/foobar/barfoo' AND
    • '/foobar/../barfoo' becomes '/barfoo'
  2. URL-encode the remaining path using the UTF-8 character set in accordance with RFC 3986 with the following caveats:
    • ' ' (space) should always be '%20'
    • '*' (asterisk) should always be '%2A'
    • '%7E' should always be '~' (tilde)
  3. Empty string path should always result in ‘/’

In the Example Request, this results in:


Canonicalize the Query String

The query-string is canonicalized by the following operations:

  1. Remove the query-string from the URI (not-including the ‘?’)
  2. Construct a collection of key/value pairs by splitting the query string on ‘&’ ASCII Sort the combined “key=value” strings (not just the ‘keys’)
  3. URL encode each key and value following the Resource Path (RFC 3986) with our caveats from above
  4. Concatenate each key/value pair like this: {key}={value}
    • If the key has no accompanying value, should result in ‘{key}=’ Join all key/value pairs with a ‘&’ in between

In the example request, this results in the empty string.


If a request contains the following query parameter,

?from=4151234567&to=4157654321&message=Thanks for your order

The canonicalized query string would be the following:


Canonicalize the Headers

The headers are canonicalized by the following operations:

  1. Filter the complete list of headers against the ‘hrh’ (hashed request headers) value in the enclosing JWT
  2. Lower-case and trim each header key
  3. Trim each header value and reduce continuous whitespace into a since space
  4. Sort header values that correspond to the same key
  5. Combine the key/values like this: “{key}:{values}\n”
  6. ASCII sort
  7. Note that because each header line is terminated with a ‘\n’. When the entire canonical request is combined, there should be a blank-line between the canonical-headers and the canonical-hashed-headers

In the Example Request, this results in:


Canonicalize the Hashed Headers

The hashed-headers are canonicalized by the following operations:

  1. Split on ‘;’ (semi-colon)
  2. Lowercase and trim
  3. 1ASCII Sort
  4. Join with ‘;” (semi-colon)

In the Example Request assume the want to include ‘Host’ and ‘Authorization’ in the list of hashed-headers, this results in:


Encode the Request Body

If the request body is empty, omit hashing it.

To encode the request body:

  1. Hash the request body using SHA-256
  2. Hex-encode the resulting hash

In the Example Request, this results in:


Final Canonical Request

In the example below, the first blank line is due to not having any query parameters. The second blank line is due to every canonicalized header being terminated with a ‘\n’.




Canonical Request Hash

When the final canonical request string is created it must be hashed in a similar manner to the request body.

To encode the canonical request:

  1. Hash the request body using SHA-256
  2. Hex-encode the resulting hash

In the Example Request, this results in:


4. Generate the JWT

Once you have created the hash, you can generate a JWT with the hash embedded.

Every JWT assertion is composed of three components, the header, the payload, and the signature.

  • The header specifies the algorithm used for the JWT signature.
  • The payload contain the hash and additional metadata
  • The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

To construct the JWT assertion, these three components must be base64 encoded and concatenated using a “.” separator:

<base64URLencoded header>.<base64URLencoded claims>.<base64URLencoded signature>

Note: For additional details on JWT go to:

Let’s have a closer look at the different parts of the JWT Assertion:


The header consists of four parts: the content type, type of the token, the hashing algorithm being used, and the reference to the public key Twilio should used validate the message.

Field Value(s) Required Description
cty twilio-pkrv;v=1 yes ContentType = Twilio Public Key Request Validation - Version 1
typ JWT No (Default: ‘JWT’) Media Type = JSON Web Token, other values rejected
alg RS256 yes Algorithm = RSASSA-PKCS-v1_5 using SHA-256 hash algorithm. This is the only algorithm supported at the moment.
kid CredentialSid yes Key ID = Identifier of the public key credential associated with the private key used to sign the JWT

Example header:

  "cty": "twilio-pkrv;v=1",
  "typ": "JWT",
  "alg": "RS256",
  "kid": "CR00000000000000000000000000000000"


The second part of the token is the payload, which contains the claims. Claims are statements about an entity and additional metadata.

Field Value(s) Required Description
iss APIKeySid yes Issuer = APIKey Sid used to match against request credentials
sub AccountSid yes Subject = AccountSid
exp expiration time yes Token Expiry Time: token received after exp +- clock skew will be rejected. Max exp - nbf is 300 seconds
nbf not before time No (Default: ‘now’) Not Before Time
hrh list of headers to hash yes A ‘;’ (semicolon) delimited list of lowercase headers to include in the request hash calculation. At a minimum you must include ‘Host’ and ‘Authorization’
rqh request hash yes Please refer to ‘3. Create Hash of the Canonical Request’ above.

Example Payload:

  "iss": "SK00000000000000000000000000000000",
  "sub": "AC00000000000000000000000000000000",
  "exp": 1471827354,
  "hrh": "authorization;host",
  "rqh": "245eece1e638d9b0081ca0621183cd417fc97a1818bd822aa26697f9aa70c792"


To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

Signature Creation Example

  base64UrlEncode(header) + "." +

Public Key

To validate the signature Twilio needs the public key. This public key needs to be uploaded to Twilio. The public key must be:

  • Algorithm: RSA
  • Modulus::bitLength: 2048
  • Format: X.509

Public key to successfully validate the Example JWT (below):

-----END PUBLIC KEY-----

Private Key

The request has to be signed with a private key. The private key must match the public key uploaded to Twilio.

There are no limitations on the private key (as opposed to the public key, enumerated above) other than it needs to match the public key. It can be either PKCS#1 or PKCS#8 (whichever the signing library supports).

Private key used to sign the Example JWT:


Example JWT

The following JWT is composed of the example blocks from above. The JWT is signed with the private key above. This JWT can be validated with the public key above.


5. Attach JWT to the Request Header

The JWT needs to be added to the request via the Twilio-Client-Validation header.

Client Validation Java Example

The functionality is currently only supported in the latest Java helper library.

The following example covers all five steps of making a successful Client Validation request. This sample is also available on Github.

package com.twilio.example;

import com.twilio.http.TwilioRestClient;
import com.twilio.http.ValidationClient;
import com.twilio.twiml.TwiMLException;
import com.twilio.type.PhoneNumber;
import org.apache.commons.codec.binary.Base64;


public class ValidationExample {

    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
    public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");

     * Example Twilio usage.
     * @param args command line args
     * @throws TwiMLException if unable to generate TwiML
    public static void main(String[] args) throws Exception {

        // Generate public/private key pair
        KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
        KeyPair pair = keyGen.generateKeyPair(); pk = pair.getPublic();

        // Use the default rest client
        TwilioRestClient client =
            new TwilioRestClient.Builder(ACCOUNT_SID, AUTH_TOKEN)

        // Create a public key and api key using the default client
        PublicKey key = PublicKey.creator(
        ).setFriendlyName("Public Key").create(client);

        NewKey apiKey = NewKey.creator().create(client);

        // Switch to validation client as the default client
        TwilioRestClient validationClient = new TwilioRestClient.Builder(apiKey.getSid(), apiKey.getSecret())
            .httpClient(new ValidationClient(ACCOUNT_SID, key.getSid(), apiKey.getSid(), pair.getPrivate()))

        // Make REST API requests with Client Validation enabled
        Iterable<Message> messages = Message.reader().read(validationClient);
        for (Message m : messages) {

        Message m = Message.creator(
            new PhoneNumber("+1XXXXXXXXXX"),
            new PhoneNumber("+1XXXXXXXXXX"),
            "Client Validation Test"


Standard API Keys are not permitted to manage Accounts (e.g. create sub accounts) and other API Keys. If you require this functionality please refer to this page for additional details.

It may take a few minutes after Enforcing Public Key Client Validation from Settings for it to take effect.

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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Loading Code Sample...

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!