Authentication
Try the API Explorer
APIs
SMS API
SMS Verify API
Bulk SMS API
Anonymous SMS API
Voice API
Voice Verify API
Phone Numbers API
PhoneID API
Score API
App Verify API
Get Status API
Completion API

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 your Technical Account Manager.

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-ww.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 (Java, Python, Ruby, PHP, C#), then authentication is handled for you and you do not need this page.

NOTE:

If you are using rest.telesign.com endpoints, TeleSign recommends that you upgrade to the new base URI rest-ww.telesign.com as soon as possible. It is faster.

Example of a GET Request
GET https://rest-ww.telesign.com/v1/phoneid/standard/15555551234 HTTP/1.1
Accept-Encoding: gzip,deflate
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 17:52:41 GMT
User-Agent: Jakarta Commons-HttpClient/3.1
Host: rest-ww.telesign.com

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:

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:

HTTP
Authorization = "TSA " + " " + Customer ID + ":" + Signature

Obtain Customer ID and API Key

If you have an account with TeleSign, you have a customerID. If you forget it, log in to TelePortal. Your customerID appears in the Organization - Account Page section. This is also where you go to create your API key.

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-ww.telesign.com/v1/verify/sms 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/verify/sms 
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-ww.telesign.com/v1/verify/smsin your request-line, and the message body for POST is phone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$, then the canonicalized POST request looks like this:

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
phone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$\n
/v1/verify/sms
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.

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-ww.telesign.com/v1/verify/smsin your request-line, and the message body for POST is phone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$, then the canonicalized POST request looks like this:

Canonicalized POST 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
phone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$\n
/v1/verify/sms
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 real time, 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.
  1. 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-ww.telesign.com/v1/some/resource?option=value&parameter=something

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

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
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 a Verify GET request that looks like this:

Verify GET Example Request
GET https://rest-ww.telesign.com/v1/verify/AEBC93B5898342F790E4E19FED41A7DA?verify_code=57244 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Host: rest-ww.telesign.com
Date: Tue, 31 Jan 2017 19:36:42 GMT
Authorization: TSA AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:CIq6B7fGwDDkAc4Pl5/NxQe0hnA=

StringToSign looks like this:

Verify GET StringToSign Example
GET\n
\n
Tue, 31 Jan 2017 19:36:42 GMT\n
x-ts-auth-method: HMAC-SHA256\n
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 a Verify SMS POST request that looks like this:

Verify SMS POST Example
POST https://rest-ww.telesign.com/v1/verify/sms HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 92
Host: rest-ww.telesign.com
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: fb$JFha/oe475+GG2fd
X-TS-Date: Tue, 31 Jan 2017 11:36:42 GMT
Authorization: TSA AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=

phone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$

StringToSign looks like this:

application/x-www-form-urlencoded\n
\n
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
phone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$\n
/v1/verify/sms
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 Authorization 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:

GET Request Header
GET https://rest-ww.telesign.com/v1/phoneid/standard/15555551234 HTTP/1.1
Accept-Encoding: gzip,deflate
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 17:52:41 GMT
User-Agent: Jakarta Commons-HttpClient/3.1
Host: rest-ww.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.

Verify GET Example

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

Verify GET Request
GET https://rest-ww.telesign.com/v1/verify/AEBC93B5898342F790E4E19FED41A7DA?verify_code=57244 HTTP/1.1
Host: rest-ww.telesign.com
Date: Tue, 31 Jan 2017 19:36:42 GMT
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:CIq6B7fGwDDkAc4Pl5/NxQe0hnA=
Verify GET StringToSign
GET\n
\n
Tue, 31 Jan 2017 19:36:42 GMT\n
x-ts-auth-method: HMAC-SHA256\n
/v1/verify/AEBC93B5898342F790E4E19FED41A7DA
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 “Verify GET StringToSign” are provided for reading clarity. When you set this up, the \n would be the only break between each piece of information.

Verify SMS POST Example

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

Verify SMS POST
POST https://rest-ww.telesign.com/v1/verify/sms HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 92
Host: rest-ww.telesign.com
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: fb$JFha/oe475+GG2fd
X-TS-Date: Tue, 31 Jan 2017 11:36:42 GMT
Authorization: TSA AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=

phone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$
Verify SMS 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 11:36:42 GMT\n
x-ts-nonce:fb$JFha/oe475+GG2fd\n
phone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$\n
/v1/verify/sms
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 “Verify SMS 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, 10 Jan 2012 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

The TeleSign server returns the following header fields:

Allow - Indicates the HTTP methods that the resource supports. The allowed methods for verify/bulk_sms are POST.

Content-Type - Specifies the media type of the response message’s payload (that is, of the data contained in the response message’s entity-body). TeleSign web services always return results in the application/json data format.

Authenticated Callbacks with the Transaction Callback Service

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 the Authorization: header.

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)

Signature Verification in Python and Java for Authenticated Callbacks

Here is an example of how to verify the signature of the JSON string in the callback using Python and Java:

from base64 import b64decode, b64encode
from hashlib import sha256
from hmac import HMAC

def verify_telesign_postback(ts_api_key, http_headers, json_str):
   """Verify that a Callback request was made by TeleSign, and was not sent by a malicious client.

   @param ts_api_key: the shared TeleSign API Key used to make the original
   TeleSign REST transaction, or it is the API Key for a specific product.

   @param http_headers: a dictionary of the HTTP POST Request headers,
   supplied by whatever HTTP request processing framework you use.

   @param json_str: the POST body text, that is, the JSON string sent by
   TeleSign describing the transaction status.
   """
 sig1 = headers['X-TS-Authorization']
   mac = HMAC(b64decode(ts_api_key),
          json_str,
          sha256)
   sig2 = b64encode(mac.digest())

   # Use the supplied hmac.compare_digest function, if available on your platform.
   # @see:
   # https://docs.python.org/2/library/hmac.html#hmac.compare_digest
   if hasattr(hmac, 'compare_digest'):
     return hmac.compare_digest(sig1, sig2)

   else:
     # Do char-by-char compare, and don't short-circuit the comparison. 
     # @see:
     # http://codahale.com/a-lesson-in-timing-attacks/
     if len(sig1) != len(sig2):
          return False

     res = 0
     for i in range(0, len(s1)):
          # NOTE: every char in Base64 is ASCII-compatible, hence the
          # call to ord()
          res |= (ord(sig1[i]) ^ ord(sig2[i]))
     return res == 0