API Reference - TextKey™ APIs

Overview

TextKey is a system that provides omni-factor authentication (OFA) to various one-factor authentication (password-only) systems. The most common of those is providing OFA to a web site or Virtual Private Network (VPN) via enhancements to the login page. There are other authentication systems however, such as providing OFA to door code locks for secure entry to buildings, for which TextKey works equally well.

A basic tenet of the TextKey system is that the basic authentication token (userId for web pages, door code for door codes, etc.) be associated with at least one Cell Phone Number. That association can be made in a customer authentication database such as Active Directory, an LDAP database, a customer provided proprietary system or in a TextKey provided database. The choice of which database to use is dependent upon many factors such as the current operation of the customer's basic authentication system, the degree of technical expertise available to the customer, the TextKey features that the customer wishes to use, etc.

TextKey Operational Options

API Modes

doesRegistrationuserIDExist

TextKey provides 2 types of essentially identical API interface methods: RESTful and SOAP/Web services. These API methods can be used interchangeably; for example you can use the SOAP services on the server side and the RESTful services on the client side.

RESTful Services

All TextKey RESTful service commands take a JSON object on the input and return a JSON object. Authentication is by means of an API key for all calls. All RESTful calls must be made via the POST method.

The TextKey RESTful interface is found at:

https://secure.textkey.com/REST/TKRest.asmx/CommandName where CommandName is replaced by the applicable command name.

The input JSON object is sent as a body document on the POST (i.e. there is no query string parameter). All calls are authenticated using an API Key.

An API key is a string of the format: 9021fa44-f1bc-4590-b975-42fee031e078 . The first parameter of all input objects is the API Key.

Output objects all have an errorDescr string item returned. If the string is zero length, no error occurred. If the string length is greater than zero, an error occurred as described in the string. When an errorDescr is returned, all other parameters in the return object should be regarded as invalid.

Communication with RESTful Services

Sending To RESTful Services

All API calls and their parameters on the RESTful services should be regarded as case sensitive and take a single JSON parameter called DataIn. Using the doesRegistrationuserIDExist API call as an example, the JSON string would look like:

{
    "DataIn": {
        "apiKey": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
        "userID": "ABC123EFG",
        "isHashed": "true"
    }
}

Return Data from RESTful Services

All API call payloads on the RESTful services are wrapped in an element called d. Using the doesRegistrationuserIDExist API call as an example, the JSON return payload will look like:

{
    "d":{
        "__type":"TextKeyCommon.TKStructures+RegistrationExistence",
        "cellNumberCount":-2,
        "userIDCount":1,
        "errorDescr":""
    }
}

SOAP/Web Services

This manual will not attempt to describe the general SOAP interface and structure. It is expected that the reader already knows this. This manual provides only supplementary information that is not found in the WSDL descriptions. This interface along with the other SOAP interfaces allows the TextPower (TPI) customer to build extremely sophisticated messaging applications. Building a SOAP interface should not be undertaken unless the developer has the proper development tools to auto-generate the necessary interface code and the expertise to develop the SOAP application.

TextKey SOAP functions return a structure. Authentication can be done via an API Key or by a SOAP Header. All functions come with both a header variant and an API Key variant denoted by the function call name ending with _Key. A SOAP header is required on all calls not using the _Key variant of each call and the header information is identical on all calls. _Key calls do not require a SOAP header. SOAP exceptions are supported. SOAP exceptions always represent internal program errors. Please check the information that you are supplying to correct this type of problem.

SOAP/XML Web Service - WSDL and Header

The WSDL document for the TextKey SOAP interface is located at: https://secure.textpower.com/TPIServices/TextKey.asmx?wsdl

The address for the SOAP calls on the TextKey interface is: https://secure.textpower.com/TPIServices/TextKey.asmx

All TextKey functions come in two varieties with the difference in how the authentication is handled. Function calls without a _Key suffix use the standard TextPower SOAP header for authentication. Functions with _Key on the end use an API Key for authentication.

SOAP/XML Web Service - SOAP Header

The SOAP header on all calls has four parameters as described in the WSDL. All header parameters are of type String.

Parameter Value Required
UID The value of your userId as assigned by TPI. Yes
PWD The value of your password as assigned by TPI. Yes
Campaign The name of the campaign you are using for this call. If you have only one campaign, this parameter may be a zero length string. No
Keyword The keyword in your campaign that you are using for this call. If you have only one keyword in your campaign, this parameter may be a zero length string. No

Here is an example of what the SOAP header should look like for a UID/PWD SOAP request.

API Key

An API Key is a special 128 bit number that serves as a login key. You may obtain an API key in the following ways:

  1. You can create a an account on this site and once you have created an account, you can get a Developer API Key by going to User Settings and following the instructions on the API Information tab. This is strickly a Developer API Key and can be used for development purposes only per the API Developer Terms of Service.
  2. You may obtain a permanent API Key by logging on to the TextPower customer web site at https://customer.TextPower.com and visiting the page Campaigns | API Key. This option is only available to TextPower customers with paid accounts. To find out more about getting a permanent API Key, go to our Contact Us page.
  3. The getTempAPIKey function can return a temporary API Key that you can use in later pollForIncomingTextKey calls. This temporary API Key is valid for a maximum of 9 minutes although you can specify a lower duration. You must have a permanent API Key or set of UID/PWD credentials in order to use this option.

An API Key will look like this example: 9021fa44-f1bc-4590-b975-42fee031e078. It may or may not be surrounded with curly braces {}.

Here is an example of what the SOAP header should look like for an API SOAP request.

TextKey Modes of Operation

TextKey can be used to provide many levels of security via Omni-factor authentication. This can range from very simple authentication methods to protect less secure operations to very extensive modes for protecting complex operations or those needing heightened security. The TextKey authentication factors beyond any standard user authentication factors such as UserID/Password, Door Key, etc. are:

Factor Status Standard Mode
Phone UDID confirmation Always Yes
Mobile Number Verification Always Yes
TextKey Selected Yes
Pin Code Selected No
Distress Pin Code Selected No
Dynamically Assigned Destination Optional No
Hidden Self-Destructing link to get key Optional No
Anything Response Selected No
Verification via Touch Tone Landlines Optional No
Call Center Verification Optional No

For Mobile Number verification, TextKey supports numbers worldwide.

TextKey supports destinations (the number that the TextKey or other is sent to) standard in the US, Canada and the United Kingdom. If you need sending destinations in other parts of the world, those can be arranged although a modest additional charge may apply.

The Selected group above refers to options detailing the input information that must be supplied by the user in the group below that may be selected. One selection must be made from the group below that is ordered from highest security to lowest.

User Input Selections. (One option must be selected)

  1. Both a TextKey and a user selected Pin Code or Distress Pin Code must be supplied. (Highest security)
  2. TextKey: A displayed one time TextKey must be supplied.(Excellent Security)
  3. Anything sent back from a registered phone will authenticate. (Good Security)

Mixed Client and Server Mode

The standard Mode of TextKey is designed to provide a very quick and minimum effort to a customer wishing to implement TextKey. It can be implemented with only a very minimal change to the customer's existing logon scheme and runs partially on the client side and partially on the server side. On the server side, only 2 simple API calls are necessary. A plug and play client JavaScript package provided by TextKey or one of your own design must be installed on the client side. No coding is required for the TextKey client package although some basic data parameters must be set.

On the other side, simplification brings standardization. The TextKey basic mode does not allow Pin Codes, Distress Pin Codes or full Omni-factor authentication, Call Center access or control over the validity period of the TextKeys. The validity period of all TextKeys is 130 seconds. Experience has shown that a TextKey can be entered on a cell phone in less than 30 seconds so the Basic Mode provides a 4:1 margin on time.

Server Only Mode

It is possible to implement all TextKey API calls from the server side only. In a standard Web Login protection application however, it will be necessary to have the web login page poll for the reception of the TextKey by some means. Using a temporary API key, this can be done easily on the RESTful interface with the pollForIncomingTextKey function. If you do not wish to run the poll directly from the client site, you may use a AJAX style call of your own design to execute the poll on the server side.

Function Calls

Type specifications for each call and the parameter data types can be viewed in the API Documentation page. The basic purpose of each function, the input and output options, and sample output and sample code are also described in the in the API Documentation pages.

Note that in the case of SOAP requests (per the WSDL), the Integer type is referred to as int, the Date type is referred to as DateTime and the XmlNode type is a complex type. They are the same thing and may be used interchangeably.

In all function calls, a string parameter called apiKey appears as the first parameter for all functions whose name ends in _Key. This Authorization or API key can be obtained from one of two sources:

  1. A temporary API key can be obtained from the issueTextKeyFromUserId or issueTextKeyFromCellNumber functions.
  2. A permanent API key can be obtained from the TextPower customer web site.

For all functions, except the createNewCellNumberProxy, which have an input parameter called cellNumber, the Cell Number may be either a Cell Number or a Cell Number proxy. It is recommended that for all API calls issued in a relatively unsecure environment such as a browser, the Cell Number proxy be used. The createNewCellNumberProxy functions return a Cell Number proxy for use in later calls. This call should only be used on the server side and should be needed only when using the Cell Number API call options.

API Functions-General

Organization of TextKey API Calls

TextKey is designed to provide services to a wide variety of platforms. In addition it is designed to adapt to the wide variety of server and customer situations in existence. While the list of API calls may look bewilderingly large at first, any individual customer will care about only a few of them. Following are some markers to use to make your decision.

Case Conventions

Some systems and languages are case sensitive regarding names. The casing convention used in all TextKey API calls is as follows:

  1. Command names are camel cased with the first letter being lower case. This is sometimes referred to a lower camel case. E.g. doesRegistrationCellNumberExist
  2. Structure names for both input and output are camel cased with the first letter being upper case. This is sometimes referred to as upper camel case. i.e. RegistrationExistence

Web Services versus RESTful API

SOAP based Web Services have been around a while, are highly standardized and remarkably easy to use. Just point at their standard WSDL document and start coding. It is almost foolproof. For server side applications, it is hard to beat them.

However SOAP services are hard to implement on low power devices such as tablets and smartphones and trying them in a browser is fraught with trouble for many reasons not least of which is the cross origin problem.

RESTful services can be implemented from either the server or client sides on almost any kind of device. For browser or low power environments, they are nearly mandatory. On server environments, however, they are not nearly as automatic and easy to implement as services that can be connected quickly and nearly error free from a WSDL.

UserIDs versus Cell Numbers

All TextKey operations depend upon the valid authorizing Cell Numbers being registered on TextKey servers. Most API functions that deal with TextKeys have multiple versions that can work with either hashed userIDs or with Cell Numbers. The customer has their choice as to which method to use. Typically however, the choice will depend upon the server used and the needs of that particular customer. For example:

  1. If the customer's server can store the Cell Number and several other parameters for each userID, you can use the Cell Number functions although you do not have to. An Active Directory server would be able to easily use the Cell Number methods.
  2. If your server cannot store the above user information or modifying it to contain that information entails excessive work, you will need to use the userID functions. The userID functions will retrieve the Cell Number from the UserID.

Note on UserIDs and userId hashing: Regarding functions that require the userId that was entered on the TextKey registration page or registerTextKeyUser API calls. TextPower does not store your actual userId! It stores an MD5 hash of the userId by default. You may choose another hash algorithm if you wish. To retrieve the Cell Number needed for these functions the following logic is used:

  1. If the isHashed parameter is False, TextPower will create the MD5 hash of the userId and use this hash to match the proper record in the TextPower registration database. This is the easiest option to use.
  2. If the isHashed parameter is True, TextPower will match the stored hash directly from the provided userId which in this case is expected to be a hexadecimal string representing the hash, not the real userId. You must use the isHashed parameter consistently for the registration process, the issuance process and the validation process! If isHashed is set to True in all cases, you may choose your own hash algorithm for the userId from among the following hash types:
    MD5 | SHA | SHA1 | SHA2_256 | SHA2_512

A Note on Languages

There are a wide variety of languages and operating systems in use today. All TextKey interfaces are built to industry standards. Standard Web Services Description Language (WSDL) is used for the SOAP Web Services interfaces and Cross Origin Resource Sharing (CORS) JSON for the RESTful interface.

Sample Authentication Flow

A basic authentication flow consists of the ability to issue and validate a TextKey.

Step 1: Issue the TextKey by calling the issueTextKeyFromUserId after the initial submit of the login page.

issueTextKeyFromUserId(“myuserid”, false)

The myuserid in this case is your own unique internal identifier for your user.

Receive back a IssueTextKeyReturn structure with elements set as below:

__type: TextKeyCommon.TKStructures+IssueTextKeyReturn
textKey: 3809802
status: 1
validationCode: 2H46D
mode: 0
receiveMode: 0
useLink: 
textToCode: 
cellNumberProxy: 
errorDescr:

The TextKey code is passed to the Login page to be displayed by the client package. The Validation Code is passed to the Login page in a hidden variable. The visual appearance of the login page remains the same on server submit. The client package will manipulate the appearance using an overlaying layer to display the TextKey and timing information.

Step 2: Monitor for the receipt of the TextKey.

The client package will monitor for the receipt of a TextKey from the registered cell phone. When a TextKey is received, the client page will submit the login page. No user code other than including the client package is required for this step.

pollForIncomingTextKey(“3809802”)

The polling code is waiting for either the time to expire or for the ActivityDetected field to return back with a true value. 

Receive back a PolledTextKey structure with elements set as below:

__type: TextKeyCommon.TKStructures+PolledTextKey
ActivityDetected: 1
TimeExpired: 
errorDescr:

Step 3: Validate the received TextKey to make sure it was an authentic request.

When the client package detects a TextKey, it will re-submit the login page. After the re-submit, execute the following function.

validateTextKeyFromUserId(”myuserid”, “3809802”, ”2H46D”, false)

Receive back a ValidateTextKeyReturn structure with elements set as below:

__type: TextKeyCommon.TKStructures+ValidateTextKeyReturn
validated: 1
validationErrors: Array
(
    [0] => textKeyNoError
)
errorDescr: