Authentication
To make calls to Telesign APIs, you must provide authentication details with each request. Telesign offers the following authentication choices (with some API operations only supporting a sub-set of these choices):
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 one or more of these methods; see the reference documentation for an endpoint to check which auth methods it supports.
NOTE:For information about authentication for the Protect Platform, see Protect Platform authentication.
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 or OAuth 2.0 authentication
Cons
- May be less secure: A successful man-in-the-middle (MITM) attack gives the attacker the opportunity to obtain your Telesign credentials.
- Allows broad access: Basic authentication using an API key allows broad access to all products enabled for your account. To comply with the principle of least privilege, you may want to use OAuth 2.0 authentication with limited scopes instead.
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 MITM attacks.
How to implement it
NOTE:These instructions include examples in Python, but the process is similar for other languages.
- 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-AB1234567890ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==- Join your Customer ID and API Key together as strings with
:in between:
'FFFFFFFF-EEEE-DDDD-1234-AB1234567890:ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==' - Encode the result with UTF-8 encoding:
'FFFFFFFF-EEEE-DDDD-1234-AB1234567890:ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==' - Encode the result with Base64 encoding:
'RkZGRkZGRkYtRUVFRS1ERERELTEyMzQtQUIxMjM0NTY3ODkwOkFCQzEyMzQ1eXVzdW1vTjZCWXNCVmtoK3lSSjVjemdzbkNlaFphT1lsZFBKZG1GaDZOZVg4a3VuWjJ6VTFZV2FVdy8wd1Y2eGZ3PT0=' - Decode the result using UTF-8 encoding
'RkZGRkZGRkYtRUVFRS1ERERELTEyMzQtQUIxMjM0NTY3ODkwOkFCQzEyMzQ1eXVzdW1vTjZCWXNCVmtoK3lSSjVjemdzbkNlaFphT1lsZFBKZG1GaDZOZVg4a3VuWjJ6VTFZV2FVdy8wd1Y2eGZ3PT0=' - Add an Authorization header to your request. Its value should be
Basicfollowed by a space, followed by the encoded string you created in the previous steps.
Authorization: Basic RkZGRkZGRkYtRUVFRS1ERERELTEyMzQtQUIxMjM0NTY3ODkwOkFCQzEyMzQ1eXVzdW1vTjZCWXNCVmtoK3lSSjVjemdzbkNlaFphT1lsZFBKZG1GaDZOZVg4a3VuWjJ6VTFZV2FVdy8wd1Y2eGZ3PT0=
- 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.
- Allows broad access: Like Basic authentication, Digest authentication using an API key allows broad access to all products enabled for your account. To comply with the principle of least privilege, you may want to use OAuth 2.0 authentication with limited scopes instead.
How to implement it
NOTE:These instructions include examples in Python, but the process is similar for other languages.
- 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==
- 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-dateandDatemust be no more than 15 minutes (+/-) from the time of the request. If you include both, the service usesx-ts-dateand ignoresDate. (Required) - Content-type: The MIME type of the request payload. Depending on the specific endpoint, either
application/x-www-form-urlencodedorapplication/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)
- 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.)
- 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-SHA256GET\n\nTue, 31 Jan 2017 19:36:42 GMT\nx-ts-auth-method: HMAC-SHA256\nPOST /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!
- Save your string-to-sign to use in a later step.
- Encode the string-to-sign created in the previous steps using UTF-8 encoding.
- Base64 decode your API Key
- 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)- Create a digest from this HMAC object.
- Decode this digest with UTF-8 encoding.
- Based-64 encode the decoded digest. This is your signature. Save it for use in the next step.
- 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=- Send your request. The reference documentation for each endpoint specifies what to expect in the response for an authentication failure or authentication success.
OAuth 2.0 authentication
A request using OAuth 2.0 authentication (client credentials flow) includes a temporary access token. Your application first obtains one of these tokens using its client credentials, and then includes the token in subsequent API requests.
Pros
- May be more secure than Basic authentication
- Industry standard for machine-to-machine interaction
- Enables your application or AI agent to use a limited sub-set of your enabled products
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 OAuth 2.0 authentication takes more time than implementing Basic.
How to implement it
-
Ensure that Telesign has enabled Integrations / OAuth 2.0 for your organization. This is an organization-level setting, not an account-level setting.
-
As an Org-level admin for your organization, log into the Telesign Full-service portal.
-
Go to Settings > Integrations.
-
Select the OAuth Apps tab.
-
Create a new OAuth app for your integration and give it a descriptive name (for example: "Okta Platform - User Management"). Ensure that this integration has only the minimum scopes assigned to it to perform the tasks you want it to do.
-
Copy the Client ID and Client Secret for this integration and save them securely (for example via environment variables) in the system that will be using Telesign APIs.
-
Configure your system to request a short-lived access token as needed from the Telesign Authentication API. We recommend using Basic auth to pass the client credentials, but if necessary you can also pass them as body parameters. The value of the Basic auth header should be constructed like this: "Basic " + base64(client_id + ":" + client_credential)
POST /oidc/token Host: login.telesign.com Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck= Content-Type: application/x-www-form-urlencoded Date: Tue, 31 Jan 2017 19:36:42 GMT grant_type: client_credentialsIf successful, the API responds with an access token. The response also indicates how long the token is valid for and what scopes it has.
-
Use this token as a bearer token in your subsequent requests using Telesign API operations that require OAuth 2.0 authentication, such as the SCIM operations of the Accounts API.
GET /scim/v2/ServiceProviderConfig Host: accounts.telesign.com authorization: Bearer 3e816b8057066077b79cb29b09427345 Date: Tue, 31 Jan 2017 19:37:01 GMT
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_basicandadd_digestfunctions are defined. - verify_with_own_code.py: Use
add_basicoradd_digest(imported fromts_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.
Updated 5 days ago