Authentication

To make calls to TeleSign APIs, you must authenticate each request. TeleSign offers two authentication choices:

Security for Authentication

Transport Layer Security (TLS) is required for both Basic and Digest authentication methods. Telesign strongly recommends that you rely on standard PKI certificate path validation. Telesign does not explictly support locally pinned certificate validation. The use of locally pinned certificates can cause service disruptions/outages when Telesign certificates are required to be renewed.

If you have a configuration that requires certificate pinning, please contact support.

Basic Authentication

Basic authentication is a simple way of enforcing access controls to web resources. The client sends HTTP requests with an Authorization header containing the word ‘Basic’ followed by a space and a base64-encoded string ‘username:password’. For TeleSign, customer_id is the equivalent of username, and api_key is the equivalent of password.

Example: Authorization: 'Basic '+ b64encoded(customer_id:api_key)

For security, with basic authentication you must use HTTPS/TLS.

For headers, use Content-Type application/x-www-form-urlencoded.

All TeleSign APIs only accept UTF-8 encoded unicode characters as inputs.

An example of how you could send a request to the SMS API using Python would look like this:

# Please replace phone_number with a valid phone number and you will need to use 
# your customer ID and API key. 

curl -v POST \
"https://rest-api.telesign.com/v1/messaging" \
-d phone_number="phone number" \
-d message="You have a dentist appointment at 2:15pm" \
-d message_type="ARN" \
-u "CUSTOMER_ID":"API_KEY"

Digest Authentication

Digest authentication is more complex to set up, but can potentially offer more secure transactions. In TeleSign’s implementation, you create a request and sign it by creating a signature and adding it to your message’s Authorization header. The signature is your message authentication code (MAC). When received by TeleSign, the shared secret API key is used to hash details about the message. A successful match results in authentication.

Access to TeleSign web services is restricted. To receive results for any call you make to a TeleSign web service, you must digitally sign your request message with valid credentials. You sign a request by creating a signature and adding it to your message’s Authorization header. The signature is your message authentication code (MAC). When received by TeleSign, the shared secret API key is used to hash details about the message. A successful match results in successful authentication and a response from the TeleSign web service you called.

This section provides instructions for setting up authentication, and includes the following:

Sample Authentication Implementations

Setting up authentication from scratch is a complex process. TeleSign recommends using a TeleSign SDK to handle authentication for you. You can see a sample of how to correctly implement authentication by clicking the link for the language of your choice.

If you absolutely want to set up authentication yourself from scratch, the rest of this document walks you through the basic steps.

Summary of Authentication Instructions

This section provides a summary of the steps you will go through. The final product of your work will be the information to provide for the Authorization header, shown as part of Example of a POST Request. If you plan to use one of TeleSign’s SDKs (Node.js, Java, Python, Ruby, PHP, C#), then authentication is handled for you and you do not need this page.

Example of a POST Request
POST https://rest-api.telesign.com/v1/phoneid/15555551212 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Content-Type: application/x-www-form-urlencoded
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 14:51:26 GMT

The Authorization header is created by combining the following information:

"TSA " + your customerID + ":" + your signature

You will walk through the following steps to create the Authorization header:

  1. Obtain customerID and API key.
  • Base64 decode your API key for use.
  1. Create a canonical request, which contains:
  • CanonicalizedTsHeaders (optional, except for the X-TS-Auth-Method header)
  • CanonicalizedPOSTVariables (for POST requests only)
  • CanonicalizedResource
  1. Create StringToSign, which contains:
  • HTTP method
  • Content-Type
  • Date
  • Canonicalized request
  1. Create your signature and sign your request.

The pseudo-code for what you are doing looks like this:

Pseudo-code for Authorization Header
CanonicalizedTsHeaders = <see description, optional EXCEPT for X-TS-Auth-Method header>

CanonicalizedPOSTVariables = <see description>

CanonicalizedResource = <HTTP-Request-URI>

StringToSign = HTTP-method + "\n" +
   Content-Type + "\n" +
   Date + "\n" +
   CanonicalizedTsHeaders +
   CanonicalizedPOSTVariables +
   CanonicalizedResource

Signature = Base64( HMAC-SHA256( YourTeleSignAPIKey, UTF-8-Encoding-Of( StringToSign ) ) )

At the end, you would want to assemble the pieces to be included in the header like this:

Authorization Header Structure
Authorization = "TSA " + "Customer ID + ":" + Signature

Obtain Customer ID and API Key

If you have an account with TeleSign, you have a customer ID. If you forget it, log in to the portal https://portal.telesign.com/.

You need both to set up authentication for your requests.

After you have your API key, you must base64 decode it.

Create a Canonical Request

Create a canonical request that takes the information from your request and standardizes it. (You may want to review all the different kinds of headers your request can contain. If so, refer to the Standard and TeleSign-Specific HTTP Headers section below.)

You canonicalize your request so that the TeleSign web service you are calling can calculate the same signature that you calculated and authenticate you by matching exactly to your request.

Using the pseudo-code presented in section Summary of Authentication Instructions, the following is true:

If you use GET, your canonicalized request includes the pieces:

  • CanonicalizedTsHeaders (optional, EXCEPT for the X-TS-Auth-Method header)
  • CanonicalizedResource

If you use the example URI https://rest-api.telesign.com/v1/messaging in your request-line, then the canonicalized GET request looks like this:

Canonicalized Get Request
x-ts-auth-method: HMAC-SHA256\n
x-ts-date:Tue, 31 Jan 2017 11:36:42 GMT\n
x-ts-nonce:fb$JFha/oe475+GG2fd\n
/v1/messaging
NOTE:

Line breaks in the example “Canonicalized GET Request” are provided for reading clarity. When you set this up, the “\n” would be the only break between each piece of information.

If you use POST, your canonicalized request includes the pieces:

  • CanonicalizedTsHeaders (optional, EXCEPT for the X-TS-Auth-Method header)
  • CanonicalizedPOSTVariables
  • CanonicalizedResource

If you use the example URI https://rest-api.telesign.com/v1/messaging in your request-line, and the message body for POST is phone_number=15555551212&message=Your message here., then the canonicalized POST request looks like this:

Canonicalized POST Request
x-ts-auth-method: HMAC-SHA256\n
application/x-www-form-urlencoded; charset=utf-8\n
x-ts-date:Tue, 31 Jan 2017 11:36:42 GMT\n
x-ts-nonce:fb$JFha/oe475+GG2fd\n
phone_number=15555551234&message=Your message here.
NOTE:

Line breaks in the example “Canonicalized POST Request” are provided for reading clarity. When you set this up, the “\n” would be the only break between each piece of information.

Create CanonicalizedTsHeaders

CanonicalizedTsHeaders contains all HTTP request headers you wish to include that start with X-TS. They are optional with the exception of X-TS-Auth-Method. You use the X-TS-Auth-Method header to specify SHA-256 for encryption. The optional headers offer the following features:

  • X-TS-Date - The TeleSign-specific option is provided because some HTTP client libraries do not support the standard HTTP Date header. If X-TS-Date is included, its value will override the value in the Date header.
  • X-TS-Nonce - for more protection against replays, you may include an X-TS-Nonce header that contains a random, unique string.

More details about these headers are provided in the section Standard and TeleSign-specific HTTP Headers.

To set up CanonicalizedTsHeaders, do the following:

  1. Decide if you will use X-TS-Date as a header. Authenticated requests require a valid time stamp. If you include X-TS-Date, its value overrides the value in the Date header. Be aware that:
    • You must use your local machine’s local timestamp.
    • You must make sure your timestamp does not drift more than +/- 15 minutes from the time used by the TeleSign server, or your request will fail.
    • You must make sure your timestamp includes the local timezone. If it is missing, the TeleSign system assumes your timezone is GMT and compares it to the timestamp.
  2. Make sure you include X-TS-Auth-Method, and set it to HMAC-SHA256.
NOTE:

SHA-256 is a Secure Hash Algorithm (SHA) defined in RFC 4636. It is available in cryptography libraries in most programming languages. The algorithm takes as input two byte-strings: a key and a message. For TeleSign request authentication, use your base64 decoded TeleSign API key, and the UTF-8 encoding of the StringToSign as the message. The output of HMAC-SHA256 is also a byte string, called the digest. The Signature request parameter is constructed by base64-encoding this digest. TeleSign supports HMAC-SHA256 encryption. To use it, you must specifically state you are using an HMAC-SHA256 encryption in the X-TS-Auth-Method header.

NOTE:

To learn more about HMAC, a mechanism for message authentication that uses cryptographic hash functions, refer to RFC2104.

  1. Convert each HTTP header name to lowercase. For example, X-TS-Date becomes x-ts-date. Only the header name has to be converted to lowercase, not its value.
  2. Sort the collection of headers alphabetically by header name.
  3. Make sure each X-TS- header appears only once.
  4. Unfold long headers that span multiple lines (as allowed by RFC 2616 section 4.2) by replacing the folding white space (including newline) by a single space.
  5. Trim any white space around the colon in the header. For example, the header x-ts-auth-method : hmac-sha256 becomes x-ts-auth-method:hmac-sha256.
  6. Assemble the CanonicalizedTsHeaders element by concatenating all X-TS- headers name:value pairs into a single string, separating them by newline - \n (U+000A) characters.

Create CanonicalizedPOSTVariables (for POST Requests)

If you are canonicalizing a POST request, then use the body of the POST request exactly as it will be sent in the request to TeleSign. It is important to be able to estimate exactly how the POST body will look when it will be sent out by your library function or your browser. The TeleSign REST API does not require you to use any specific URL encoding, but when you construct StringToSign in the next step, you must use the body of the POST request exactly as it is will be delivered to the service. You may want to use debugging proxies or port captures, and examine the raw request string if you are in doubt.

Create CanonicalizedResource

The CanonicalizedResource comes from the URI in the request-line of your request and encompasses everything in the URI from directly after .com to directly before the ? that separates the query parameters. For example, consider the request-line contains the URI:

https://rest-api.telesign.com/v1/someresource?option=value&parameter=something

In this example, the piece that would be used for CanonicalizedResource is /v1/someresource.

NOTE:

If the request you are signing has query parameters, you must not include the query parameters in the canonicalized resource.

Create StringToSign

StringToSign combines the canonicalized request you created with the HTTP method you are using, and two additional headers - Content-Type and Date.

The general structure for StringToSign is:

StringToSign Structure
StringToSign = HTTP-method + "\n" +
   Content-Type + "\n" +
   Date + "\n" +
   CanonicalizedTsHeaders (optional except for X-TS-Auth-Method) +
   CanonicalizedPOSTVariables (if POST) +
   CanonicalizedResource

To set up StringToSign, do the following:

  1. Start by adding the HTTP-method you are using.
  2. Follow the HTTP-method with a newline - \n.
  3. For Content-Type, include only the value for this header, not the name of the header (Content-Type). This header only applies for POST requests and is ignored for other kinds of requests. However, if you do not include this header in your request, you must still mark its position with a newline character - \n. This header is positional in nature, that is why the name of the header is not necessary.
  4. For Date, if you need to include both X-TS-Date and Date headers, then instead of specifying the actual Date header’s value, use a newline character - \n. This clearly indicates that the date that goes into the calculations is actually the date in the X-TS-Date header. If you use the header without the X-TS-Date header, specify the value here. This header is positional in nature, that is why the name of the header is not necessary.
NOTE:

If you use the X-TS-Date header, it overrides the Date header with its value.

  1. Add CanonicalizedTsHeaders to StringToSign.
  2. If you are doing a POST request, add CanonicalizedPOSTVariables to StringToSign.
  3. Add CanonicalizedResource to StringToSign.

StringToSign for GET

If you have an SMS GET request that looks like this:

SMS GET Example Request
GET https://rest-api.telesign.com/v1/messaging/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Date: Tue, 31 Jan 2017 14:53:26 GMT
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:CIq6B7fGwDDkAc4Pl5/NxQe0hnA=

StringToSign looks like this:

SMS GET StringToSign Example
GET\n
\n
Tue, 31 Jan 2017 14:53:26 GMT\n
x-ts-auth-method: HMAC-SHA256\n
/v1/messaging/0123456789ABCDEF0123456789ABCDEF
NOTE:

The second line is an empty line, as a placeholder for the missing Content-Type header. Also, the last line, corresponding to the canonicalized resource, does not include the URI section before /v1 and after the question mark.

StringToSign for POST

If you have an SMS POST request that looks like this:

SMS POST Request Example
POST https://rest-api.telesign.com/v1/messaging HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 59

phone_number=15555551234&message=Your message here

StringToSign looks like this:

StringToSign for SMS POST Request
POST\n
application/x-www-form-urlencoded\n
\n
x-ts-auth-method: HMAC-SHA256\n
x-ts-date:Tue, 31 Jan 2017 14:51:26 GMT\n
x-ts-nonce:fb$JFha/oe475+GG2fd\n
phone_number=15555551234&message=Your message here.\n
/v1/messaging
NOTE:

Because X-TS-Date was included, there is an empty line placeholder for the Date field. Also, note the order of X-TS-Auth-Method, X-TS-Date, and X-TS-Nonce that results after alphabetical sorting.

Create Your Signature and Sign Your Request

The pseudo code for your signature looks like this:

Signature = Base64( HMAC-SHA256( YourTeleSignAPIKey, UTF-8-Encoding-Of( StringToSign ) ) )

  1. Take the StringToSign you created and UTF-8 encode it.
  2. Make sure your API key (YourTeleSignAPIKey) is base64 decoded. If you do not decode it, authentication will fail.
  3. Use YourTeleSignAPIKey and the UTF-8 encoded version of StringToSign in an HMAC-SHA256 function to create a hash.
  4. Base64 encode the hash to create your signature (Signature).
  5. To sign your request, the Authorizaton header will be "TSA " + your customerID + “:” + Signature. An example looks like this:

Authorization: TSA 123ABC2B-0819-4XYZ-BED2-75BB13887CF6:n135MeEOwaWnkWVFWG0DFULtRLY=

In an example header, it looks like this:

Example GET Header
GET https://rest-api.telesign.com/v1/messaging HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: c5e18285-1790-4ba1-86df-cf228a0dda2b
Authorization: TSA 123ABC2B-0819-4XYZ-BED2-75BB13887CF6:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 14:59:40 GMT
Host: rest-api.telesign.com

Responses

Responses contain the standard Response-Header Fields, and always begin with one of the HTTP Response Status Codes in the Status Line.

Product API reference pages contain a section called Response Headers, that list the resource-specific response-header fields.

The response body is data structured in JSON format. It consists of individual, or arrays of, attribute:value pairs that represent the data requested. The response structure is described in the “Response Body” section of each resource’s reference page.

Authentication Examples

The examples in this section use the (non-working) credentials in the following table.

Parameter Value
CustomerID AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE
APIKey vW4G4ZmvGKby2dlowcdHxhkwy5RqwC+mfV9eVk3p

In the example StringToSign, formatting is not significant, and backslash-n (\n) signifies the Unicode code point U+000A commonly called newline.

NOTE:

The second line is an empty line, as a placeholder for the missing Content-Type header. Also, the last line, corresponding to the canonicalized resource, does not include the URI section before /v1 and after the question mark.

Line breaks in the example “Messaging POST StringToSign” are provided for reading clarity. When you set this up, the \n would be the only break between each piece of information.

Messaging POST Examples

This example is used earlier in the discussion about how to do authentication, but repeated here for reference.

Messaging POST
POST https://rest-api.telesign.com/v1/messaging HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Tue, 31 Jan 2017 14:51:26 GMT
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 59

phone_number=15555551234&message=Your message here.
Messaging POST StringToSign
POST\n
application/x-www-form-urlencoded\n
\n
x-ts-auth-method: HMAC-SHA256\n
x-ts-date:Tue, 31 Jan 2017 14:51:26 GMT\n
x-ts-nonce:fb$JFha/oe475+GG2fd\n
phone_number=15555551234&message=Your message here.\n
/v1/messaging
NOTE:

Because X-TS-Date was included, there is an empty line placeholder for the Date field. Also, note the order of X-TS-Auth-Method, X-TS-Date, and X-TS-Nonce that results after alphabetical sorting.

Line breaks in the example “Messaging POST StringToSign” are provided for reading clarity. When you set this up, the \n would be the only break between each piece of information.

Standard and TeleSign-Specific HTTP Headers

This section provides details about the different headers you can use.

There are two types of headers for requests:

  • Standard HTTP Headers
  • TeleSign-specific HTTP Headers

Standard HTTP Headers

The following standard HTTP headers are used for signing the request:

Content-Type

Specifies the media type of the request body data. Content-Type is required in POST requests, and must be set to application/x-www-form-urlencoded; charset=utf-8. For GET requests, do not include this header value (it is ignored if you do). Even though you do not use this header for GET requests, you must mark its position with a newline character (\n) when constructing the StringToSign. See the W3C standard 3.7 Media Types for more details about this header.

Date

Specifies the date and time at which the message originated. You should use the first (preferred) date/time format as described in RFC 2616 Section 3.3.1. For example:

Date: Tue, 31 Jan 2017 19:36:42 GMT

This standard HTTP header is required, unless X-TS-Date is included. X-TS-Date takes precedence if both are included. If you do not include this header value, then you must mark its position with a newline character (\n) when constructing the StringToSign.

TeleSign-specific HTTP Headers

The following headers are specific to TeleSign. Any included TeleSign headers MUST be used in StringToSign, according to the canonicalization rules.

X-TS-Date

Authenticated requests require a valid time stamp using either the standard HTTP Date header or the TeleSign-specific X-TS-Date header. The TeleSign-specific option is provided because some HTTP client libraries do not support the standard HTTP Date header. If X-TS-Date is included, its value will override the value in the Date header.

If you choose this option, the TeleSign system uses the value of the X-TS-Date header to verify the request timestamp. If you do not include X-TS-Date, the value in the Date header is used. If you include an X-TS-Date header, you must use an empty line as a placeholder for the Date header when constructing StringToSign. If neither Date nor X-TS-Date headers are found in the request, a 401 Unauthorized response is returned.

The value of the X-TS-Date header must use the first (preferred) date/time format as described in RFC 2616 Section 3.3.1.

X-TS-Nonce

Optionally, for more protection against replays, you may include an X-TS-Nonce header that contains a random, unique string. Only one request with a particular nonce in any given 15-minute window will be accepted, so nonces should be chosen in a way to guarantee their uniqueness (or high likelihood of uniqueness) within 15-minute periods. The nonce must have a minimum of 4 characters, a maximum of 256 characters, and is case sensitive. TeleSign recommends using a UUID, as described, for example, in RFC4122.

X-TS-Auth-Method

Use this header with a header value of HMAC-SHA256. This ensures that the authentication method is HMAC using SHA-256 as the hash function.

Response Headers

Allow - Indicates the HTTP methods that the resource supports. The allowed methods for v1/voice are POST and GET.

Content-Type - Indicates the content type of the entity-body transferred in the response message. TeleSign web services always use a value of application/json.

Authenticated Callbacks with the Get Status / Verify Transaction API

This section provides information about how to authenticate callbacks from TeleSign. If you do not want to do this, then ignore the X-TS-Authorization header and the Authorization header in TeleSign’s headers, and get the body of the message for processing.

NOTE:

You can use either the X-TS-Authorization header or the Authorization: TSA + Customer ID + Signature header to authenticate the callback, however TeleSign recommends that you use the Authorization: header. The Authorization: header includes the customer ID. In the future, the X-TS-Authorization header will be retired.

Just as you must digitally sign all your requests to TeleSign for authentication, TeleSign signs all of its requests for the Verification Transaction Callback web service. To do this, TeleSign callback requests include two custom authorization headers - X-TS-Authorization and Authorization:. You can choose which header to use to authenticate the callback, however TeleSign recommends that you use or switch to using the Authorization: header. In the future, the X-TS-Authorization header will be retired.

When you receive a message from the Verification Transaction Callback web service, to authenticate the callback, you process the header, and then authenticate. You use the secret API key that you and TeleSign share to hash the message and find a match. If there is a match, the message is from TeleSign, and legitimate.

Pseudo Code for Processing and Authenticating Callback from TeleSign
ts_api_key = ... # This is the TeleSign REST API Key.

# Get the signature (sig1) received in the HTTP request 
sig1 = http_headers['X-TS-Authorization']

# Compute the signature (sig2) on received JSON payload using HMAC-SHA256
mac = HMAC(Base64decode(ts_api_key),
               json_str,
               sha256)
sig2 = Base64encode(mac.digest())

# Compare the signatures 
result = HMAC.compare_digest(sig1, sig2)