Authentication

To make calls to Telesign APIs, you must provide authentication details with each request. Telesign offers the following authentication choices:

• Basic
• Digest

This page explains overall security requirements, describes each authentication method, lists the pros and cons of each, and explains how to implement each.

Each endpoint supports either one or both of these methods; see the reference documentation for an endpoint to check which auth methods it supports.

Overall security requirements

Protocol

You must use the HTTPS protocol for every request to Telesign. HTTP is not supported.

TLS and certificates

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 explicitly support locally pinned certificate validation.

❗️

WARNING:

The use of locally pinned certificates can cause service disruptions or outages when Telesign certificates are required to be renewed.

If you have a configuration that requires certificate pinning, please contact our Customer Support Team. This option is available for full-service accounts only.

IP restriction

We do not recommend restriction of your outbound requests to Telesign by IP address.

❗️

WARNING:

Restricting your outbound requests to Telesign by IP address can cause service disruptions or outages when Telesign's server-side traffic is shifted between service locations or if the relevant IP addresses change.

Basic authentication

A request using Basic authentication sends an encoded string that includes your Customer ID and API Key.

Pros

• Easiest to implement
• Better performance than Digest authentication

Cons

• May be less secure: A successful MITM attack gives the attacker the opportunity to obtain your Telesign credentials.

📘

NOTE:

Calls to Telesign must always be over HTTPS, which mitigates a commonly cited security weakness of Basic authentication. The use of Basic authentication over HTTP is especially vulnerable to man-in-the-middle (MITM) attacks.

How to implement it

📘

NOTE:

These instructions include examples in Python, but the process is similar for other languages.

1. Make your Customer ID and API Key accessible to your integration code. For help finding these items, see the support article How do I find my Customer ID and API Key?

FFFFFFFF-EEEE-DDDD-1234-AB1234567890

ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==

2. Join your Customer ID and API Key together as strings with : in between:
   'FFFFFFFF-EEEE-DDDD-1234-AB1234567890:ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='
3. Encode the result with UTF-8 encoding:
   'FFFFFFFF-EEEE-DDDD-1234-AB1234567890:ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='
4. Encode the result with Base64 encoding:
   'RkZGRkZGRkYtRUVFRS1ERERELTEyMzQtQUIxMjM0NTY3ODkwOkFCQzEyMzQ1eXVzdW1vTjZCWXNCVmtoK3lSSjVjemdzbkNlaFphT1lsZFBKZG1GaDZOZVg4a3VuWjJ6VTFZV2FVdy8wd1Y2eGZ3PT0='
5. Decode the result using UTF-8 encoding
   'RkZGRkZGRkYtRUVFRS1ERERELTEyMzQtQUIxMjM0NTY3ODkwOkFCQzEyMzQ1eXVzdW1vTjZCWXNCVmtoK3lSSjVjemdzbkNlaFphT1lsZFBKZG1GaDZOZVg4a3VuWjJ6VTFZV2FVdy8wd1Y2eGZ3PT0='
6. Add an Authorization header to your request. Its value should be Basic followed by a space, followed by the encoded string you created in the previous steps.

Authorization: Basic RkZGRkZGRkYtRUVFRS1ERERELTEyMzQtQUIxMjM0NTY3ODkwOkFCQzEyMzQ1eXVzdW1vTjZCWXNCVmtoK3lSSjVjemdzbkNlaFphT1lsZFBKZG1GaDZOZVg4a3VuWjJ6VTFZV2FVdy8wd1Y2eGZ3PT0=

7. Send your request. The reference documentation for each endpoint specifies what to expect in the response for an authentication failure or authentication success.

Digest authentication

A request using Digest authentication sends a hashed signature, which includes some components of the request as well as your authentication credentials. Because the hash is intended to be irreversible, the receiver uses the same components and method to create their own "expected signature", and checks that both are identical. An attacker intercepting the request who does not know the Customer ID and API Key should be unable to reverse the hash and gain access to those credentials.

Pros

• May be more secure than Basic authentication

Cons

• Usually not as performant as Basic authentication
• Harder to implement: Depending on your experience level and the libraries you are using, you may find that implementing Digest authentication takes more time.

How to implement it

📘

NOTE:

These instructions include examples in Python, but the process is similar for other languages.

1. Make your Customer ID and API Key accessible to your integration code. For help finding these items, see the support article How do I find my Customer ID and API Key?.

• Example Customer ID: FFFFFFFF-EEEE-DDDD-1234-AB1234567890
• Example API Key: ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==

2. Prepare your request, including all headers except the Authorization header (we’ll add that in a later step). Keep in mind the following requirements for headers when constructing a request for Digest auth:

• Date or x-ts-date: A timestamp generated for this request. x-ts-date and Date must be no more than 15 minutes (+/-) from the time of the request. If you include both, the service uses x-ts-dateand ignores Date. (Required)
• Content-type: The MIME type of the request payload. Depending on the specific endpoint, either application/x-www-form-urlencoded or application/json. (Required for POST and PUT requests)
• x-ts-auth-method: The hash function you wish to use. "HMAC-SHA256" is recommended, but "HMAC-SHA1" is also supported. (Required)
• x-ts-nonce: A single-use, random string, such as a uuid. It's important to include this to defend against replay attacks! (Recommended)

3. Save values of the following properties from the request:
   • http-method (POST, GET, etc.)
   • content-type (from the Content-type header)
   • auth-method (from the x-ts-auth-method header)
   • nonce (from the x-ts-nonce header)
   • date or x-ts-date Convert this to GMT. (from the header of the relevant name)
   • body Convert this to a string in UTF-8 encoding before saving. (Do not include this if there is no body or the body is equal to empty string ("").)
   • path (Include everything after the top-level domain (ex: ".com") and before the "?" separator in front of the query string.)
4. Prepare the "string-to-sign". The "string-to-sign" includes key components of your prepared request concatenated together as a single string, with some special formatting rules. This is the concatenation format for your string-to-sign:

http-method + "\n" + content-type + "\n" + date + "\n" + "x-ts-auth-method:" + auth-method  + "\n" + "x-ts-date:" + date + "x-ts-nonce:" + "\n" + body + "\n" + path

Header names must be in lower case only. HTTP method names must be in upper case.

🚧

CAUTION:

If you omit an optional property from your string-to-sign, because it is not included in your request, you must still include the "\n" separator if one comes after it! This is necessary because the service parses the string-to-sign based on those separators.

GET /v1/verify/AEBC93B5898342F790E4E19FED41A7DA?verify_code=57244
Host: rest-ww.telesign.com
Date: Tue, 31 Jan 2017 19:36:42 GMT
X-TS-Auth-Method: HMAC-SHA256

GET\n\nTue, 31 Jan 2017 19:36:42 GMT\nx-ts-auth-method: HMAC-SHA256\n

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

POST\napplication/x-www-form-urlencoded\n\nx-ts-auth-method: HMAC-SHA256\nx-ts-date:Tue, 31 Jan 2017 11:36:42 GMT\nx-ts-nonce:fb$JFha/oe475+GG2fd\nphone_number=4445551212&language=en-US&verify_code=1234&template=Your+Code+is+$$CODE$$\n/v1/verify/sms

🚧

CAUTION:

Be sure that all headers in your string-to-sign beginning with "x-ts-" are in alphabetical order. Authentication fails if these headers are not in alphabetical order!

5. Save your string-to-sign to use in a later step.
6. Encode the string-to-sign created in the previous steps using UTF-8 encoding.
7. Base64 decode your API Key
8. Create a new HMAC object using your decoded API Key, your string-to-sign, and the same "auth-method" string you included in the string-to-sign earlier. Here's an example of how you might do that in Python:

hmac_obj = hmac.new(decoded_api_key, encoded_string_to_sign, digestmod=auth_method)

9. Create a digest from this HMAC object.
10. Decode this digest with UTF-8 encoding.
11. Based-64 encode the decoded digest. This is your signature. Save it for use in the next step.
12. Add a new "Authorization" header to your prepped request. Its value should follow the format 'TSA' + a space + Customer ID + ':' + signature.

Authorization: TSA AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE:n1oBUjEwVunkjfH9paeA9qHrjQw=

13. Send your request. The reference documentation for each endpoint specifies what to expect in the response for an authentication failure or authentication success.

Sample code

Feel free to copy this Python code for adding authentication headers to requests to Telesign and adapt it to your integration:

• ts_auth.py: This is where the add_basic and add_digest functions are defined.
• verify_with_own_code.py: Use add_basic or add_digest (imported from ts_auth.py) here to add auth headers to your prepped request before you send it. This specific example uses Telesign SMS Verify API.

See also

Authentication for SDKs

If you use a Telesign SDK to make your request, authentication is handled behind-the-scenes for you. All you need to provide is your Customer ID and API Key. The SDKs apply Digest authentication whenever they make a request to a Telesign service where it is supported.

Authentication for requests from Telesign

You can also use Digest authentication to authenticate requests from Telesign to a Transaction Callback Service that you control. To learn how to do that type of authentication, see the Authentication section on Transaction Callback Service.