Skip to content

REST API

Getting Started

This REST API provides an application access to the TickStream.KeyID behavior analytics services via simple HTTP requests. To use the this API, it is important that you understand the basics of RESTful web services and JSON data representations.

Access to the TickStream.KeyID API requires a valid license key. Please contact us at developer@intensityanalytics.com for more information.

Guidelines

Compliance

Any and all use of the TickStream.KeyID API implies consent to the terms of the Intensity Analytics End-User License Agreement (EULA). Any modification of the results produced from the TickStream.KeyID API, including client libraries, may result in degraded performance, and may also result in a void of warranty.

Platforms

As it is accessible through REST, the TickStream.KeyID API may be consumed by a variety of development platforms, including Microsoft.NET (VB,C#, etc.), Java, JavaScript, Perl, PHP, Python, Ruby, and many others. However, for the sake of security practice, we strongly recommend accessing these services from a compiled application whenever transmitting your license key, or any other sensitive data, to protect that information from the client.

Cross-Origin Resource Sharing (CORS)

The TickStream.KeyID API supports CORS. This enables JavaScript code served from a domain other than the server hosting this API to make Ajax requests to it. However, with limited exceptions (the client library, validation, etc.), we strongly urge developers to use a compiled application to access these services.

Secure Sockets Layer (SSL)

Secure connection to the server hosting the TickStream.KeyID API is controlled by the configuration of that server. Access through both SSL and TLS are fully supported, provided the server has a valid certificate, and the appropriate TCP ports are open to the application.

Support

Priority support is available with a paid subscription. Please contact us at developer@intensityanalytics.com for more information. For community support, access our customer forum at http://intensityanalytics.com/forum.

Resource Summary

Click any resource to jump to that section.

  • Cohesion retrieve a visualization of the Profile status for a given EntityID.
  • Evaluate compare a given effort to the Profile for an existing EntityID.
  • Library retrieve the JavaScript client library for TickStream.KeyID operations.
  • Monitor store a given effort for offline measurement or reporting.
  • Profile create and manage the Profile for a given EntityID.
  • Token request and manage tokens as required for certain TickStream.KeyID operations.
  • TypingMistake record typing mistakes for tracking and auditing.
  • Validation test a given effort against both construction and behavior rules.

Cohesion

The Cohesion method returns information about the current status of a Profile, as visualized by displaying the member samples in graph showing the number of used (qualified) and not used (non-qualified) in the Evaluation process. Optionally, this information can also be consumed as data.

GET

URI

/profile/EntityID

URI Parameters

EntityID
Unique identifier provided for the Profile to be accessed. This can be any alphanumeric value, but may need to be URL encoded.

Return (optional)
Expects one of the following values:

  • image (default)
    This is the default Return, if the parameter is not present. The response will be in the form of a Portable Network Graphics (PNG) format image which shows the various member samples of the Profile, and how many of them are used for Evaluation.

  • value
    Returns the results in a JSON formatted array.

Data Parameters

none

Success Response

  • Return parameter set to image (default): The bitmap image of the result.

  • Return parameter set to value: [{""Error": "", "Count": (Integer), "Cohesion":"(Double)", "Qualified": (Integer), "NonQualified": (Integer)}]

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client.

  • Return parameter set to image (default): ERR | Error message (String).

  • Return parameter set to value: [{"Error": "Error message (String)"}]

Sample

 http://keyid-services.anycorp.com/cohesion/johndoe@anycorp.com?return=value

returns

[{"Count":35,"Cohesion":"0.822951","Qualified":31,"NonQualified":4}]
POST

Not used, and disabled, returns nothing.

PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

Profile

Used for managing a particular Profile, as identified by the given EntityID. When using the POST verb, it will automatically create a new profile record, or append an existing one. If the Profile already exists, it will reject the current sample if it represents a different input pattern (such as a different password).

GET

URI

/profile/EntityID

URI Parameters

EntityID
Unique identifier provided for the Profile to be accessed. This can be any alphanumeric value, but may need to be URL encoded.

Data Parameters

none

Success Response

Returns a JSON formatted list of Profile statistics.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client. Otherwise, the error will be returned as a JSON format string in the form: [{"Error": "Error message (String)"}]

Sample

 http://keyid-services.anycorp.com/profile/johndoe@anycorp.com

returns

[{"cohesion":"0.860951","qualified":12,"nonqualified":4,"lastdatetime":"2016-04-09t13:09:35.587","isready":"true","optimized":true}]
POST

URI

/profile

URI Parameters

none

Data Parameters

License
The TickStream.KeyID license code value.

EntityID
Unique identifier provided for the Profile to be accessed. This can be any alphanumeric value.

Action (optional)
Expects one of the following values:

  • add (default)
    This is the default Action, if the parameter is not present. It will add the given sample to an existing Profile, or create a new Profile automatically. This Action requires the tsData parameter, and may require the Code parameter, obtained from the Token REST method, if the time since the last update to this Profile exceeds the minutes defined by EnrollmentCodeExpiration, as set in the web.config file on the server.

  • optimize
    Reserved for future use. It will return a response, but the Profile is not modified.

  • remove
    This will remove an existing Profile. This Action requires the Code parameter, obtained from the Token REST method.

tsData (optional based on Action value)
The serialized, compressed behavior values, as returned from the populateControlWithKeyDataConcatenated function in the TickStream.KeyID jQuery library, or an equivalent.

Code (optional)
Any special token value that may be required by the given Action parameter, such as an Update code that was obtained from the Token REST method.

PasswordOpinion (optional)
A Boolean value that determines if the response includes opinion detail about the given RawText value. This includes information about meeting the basic password requirements, as well as more advanced analysis about the suitability of the password.

RawText (optional based on PasswordOpinion value)
The text that corresponds to the values in the tsData parameter. This value is only required if the PasswordOpinion parameter is True, and the data is encrypted when handled by the server. If obfuscated text is passed in this parameter, the opinion response will be of limited use.

Return (optional)
Expects one of the following values:

  • default
    Returns the results in a simple, pipe-delimited format.

  • JSON
    Returns the results in a JSON formatted array.

Success Response

If the Action is add (or empty), and PasswordOpinion parameter True:

  • Return parameter set to default: TRUE | Profiles (Integer) | QualifiedEntries (Integer) | NonQualifiedEntries (Integer) | Cohesion (Double) | Opinion Failure Count (Integer) | Opinion Failure Messages (String) | Opinion Information Count (Integer) | Opinion Information Messages (String) | Opinion Warning Count (Integer) | Opinion Warning Messages (String)

  • Return parameter set to JSON: [{"Error": "", "Result":"True/False", "Profiles":"(Integer), "QualifiedEntries":"(Integer)", "NonQualifiedEntries":"(Integer)", "Cohesion":"(Double)", "OpinionFailureCount":"(Integer), "OpinionFailureMessages":"(String)", "OpinionInformationCount":"(Integer), "OpinionInformationMessages":"(String)", "OpinionWarningCount":"(Integer), "OpinionWarningMessages":"(String)"]

If the Action is add (or empty), and PasswordOpinion parameter False:

  • Return parameter set to default: TRUE | Profiles (Integer) | QualifiedEntries (Integer) | NonQualifiedEntries (Integer) | Cohesion (Double)

  • Return parameter set to JSON: [{"Error": "", "Result":"True/False", "Profiles":"(Integer), "QualifiedEntries":"(Integer)", "NonQualifiedEntries":"(Integer)", "Cohesion":"(Double)"]

If the Action is optimize:

  • Return parameter set to default: Profile updated.

  • Return parameter set to JSON: [{"Error": "", "Result":"Profile updated."}]

If the Action is remove:

  • Return parameter set to default: Profile removed.

  • Return parameter set to JSON: [{"Error": "", "Result":"Profile removed."}]

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client.

  • Return parameter set to default: ERR | Error message (String).

  • Return parameter set to JSON: [{"Error": "Error message (String)"}]

Sample

given the following data submitted via POST (application/x-www-form-urlencoded)

=[{'License':'(license value)', 'EntityID':'johndoe%40anycorp.com', 'tsData':'(tsData value)', 'RawText':'mypassword', 'EnrollmentCode':'', 'PasswordOpinion':'TRUE', 'Return':'JSON'}]

returns

{"Error": "", "Result": "True", "Profiles": "1", "QualifiedEntries": "0", "NonQualifiedEntries": "0", "Cohesion": "0", "OpinionFailureCount": "0", "OpinionFailureMessages": "", "OpinionInformationCount": "1", "OpinionInformationMessages": "Text contains all or parts of 4 (4-10 letter) common words: pass, word, sword, password", "OpinionWarningCount": "2", "OpinionWarningMessages": "Text contains too-popular passwords segments (\"password\").\r\n Text contains only lower case character(s).\r\n"}
PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

Evaluate

Used for comparing a given sample to a stored Profile identified by the EntityID. This is the usual method called in production applications for second-factor authentication.

GET

Not used, returns a 404 response code.

POST

URI

/evaluate

URI Parameters

none

Data Parameters

License
The TickStream.KeyID license code value.

EntityID
Unique identifier provided for the Profile to be checked. This can be any alphanumeric value.

tsData
The serialized, compressed behavior values, as returned from the populateControlWithKeyDataConcatenated function in the TickStream.KeyID jQuery library, or an equivalent.

Nonce
The nonce value associated with this action, as obtained from the otk value in the TickStream.KeyID jQuery library, or from the Token REST method.

Code (optional)
Any special token value that may be required, such as a Reset or OTP code that was obtained from the Token REST method.

Return (optional)
Expects one of the following values:

  • default
    Returns the results in a simple, pipe-delimited format.

  • JSON
    Returns the results in a JSON formatted array.

Statistics (optional)
Expects one of the following values:

  • none
    No additional statistics are returned (only the Match value, along with the Confidence and Fidelity values).

  • basic
    Returns the basic statistics about the Evaluation process, used for fine tuning a process result.

  • extended
    Returns all the basic statistics about the Evaluation process, as well as additional statistics about the state of the Profile, used for fine tuning a process result.

Success Response

  • Return parameter set to default: True/False | Confidence (Double) | Fidelity (Double)

  • Return parameter set to JSON: [{"Error":"", "Match":"True/False", "Confidence":"(Double)", "Fidelity":"(Double)"}]
    Additional values may appear, depending on the value of the Statistics parameter.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client.

  • Return parameter set to default: ERR | Error message (String).

  • Return parameter set to JSON: [{"Error": "Error message (String)"}]

Sample

given the following data submitted via POST (application/x-www-form-urlencoded)

=[{'License':'(license value)', 'EntityID':'johndoe%40anycorp.com', 'tsData':'(tsData value)', 'Code':'', 'Return':'JSON'}]

returns

{"Error": "", "Match": "True", "Confidence": "78", "Fidelity": "77"}
PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

Token

GET

URI

/token/EntityID

URI Parameters

EntityID
Unique identifier provided for the account that will be associated with the Token to be issued. This can be any alphanumeric value, but may need to be URL encoded.

Type
Expects one of the following values:

  • otp
    This requests a Token for a one-time password that is used in place of the behavioral measurements, and supplied as the Token value in a POST action.

  • reset
    This requests a Token to unlock an account that has been disabled because of too many failed attempts over a given period, as configured on the server. It is supplied as the Token value in a POST action.

  • enrollment
    This requests a Token that allows a Profile to be updated with new samples, and is supplied as the Token value in a POST action.

  • remove
    This requests a Token for removing and Profile. It is supplied as the Token value in a POST action.

  • nonce
    This requests a unique Token that will be supplied as the Nonce value in an Evaluate POST action. This is equivalent to the otk value that is delivered in the TickStream.KeyID jQuery library.

Return (optional)
Expects one of the following values:

  • image (default)
    This is the default Return, if the parameter is not present. The response will be in the form of a Portable Network Graphics (PNG) format image of a QR barcode. The value of the barcode is equivalent to the response provided by setting the value of Return to uri. The size of the image and clear zone around the barcode are configured by settings on the server.

  • uri
    The response will be a string value that includes the fully qualified URI to either a Token processing page on the server (default), or another location as configured in the server settings.

  • value
    The response will be a string value that is the Token value only.

Data Parameters

none

Success Response

Returns a unique value, a URI, or an image based on the Return value.

Error Response

Returns 505, Internal Server Error. All errors are logged on the server for investigation, and are accessible through the management interface.

Sample

POST

URI

/token

URI Parameters

none

Data Parameters

License
The TickStream.KeyID license code value.

Token (optional)
The value that was supplied in a Token GET response.

SendTokenResponse (optional)
A Boolean value that indicates whether the server should send the Code value to the account holder to be used in the corresponding action. If the value is set to False, then some other process must be able to access that code from the database.

Action (optional)
Reserved for future use. If a value is supplied the response will be an error as described below.

EntityID (optional)
Reserved for future use. Unique identifier provided for the profile to be checked. This can be any alphanumeric value.

Code (optional)
Reserved for future use.

Success Response

Returns an empty string value.

Error Response

ERR | Error message (String) or an empty string value, depending on the nature of the error. All errors are logged on the server for investigation, and are accessible through the management interface.

Sample

PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

Library

Method to retrieve the client library, used to bind fields and create the TickStream.KeyID data values. This can be retrieved in a variety of formats and injected into a web page at runtime, or included directly by using a standard JavaScript src tag. Most of the library can be cached, and dynamic portions, such as the otk nonce variable, can be retrieved separately.

GET

URI

/library/LibraryName

URI Parameters

LibraryName
Expects one of the following values:

  • keyid
    The minified, dynamically obfuscated library most often used on production systems.

  • keyid-min
    The minified library most often used on production systems that use a cached copy.

  • keyid-verbose
    The unobfuscated library, with carriage returns intact that make it readable. This option can be disabled by configuring server settings.

  • keyid-documented
    The unobfuscated library, with carriage returns intact, and all inline documentation that make it readable. This option can be disabled by configuring server settings.

  • otk
    Returns only the otk nonce variable declaration, used in concert with a cached version of the library.

Exclude
Expects one or more of the following values:

  • otk
    This requests a version of the library that does not include the otk nonce variable, and so it can be safely cached. This requires a separate call to retrieve the otk declaration, such as http://keyid-services.anycorp.com/library/otk.

PreventEdits
This is a Boolean value, which can be set to false, and will enable the use of edit keys. This should never be used in production without understanding the impact on false negatives and general system performance.

Data Parameters

none

Success Response

Returns a string value that is the TickStream.KeyID jQuery library, formatted as specified by the LibraryName parameter.

Error Response

Returns an empty string value. All errors are logged on the server for investigation, and are accessible through the management interface.

Sample

<script src="https://keyid-services.anycorp.com/library/keyid"></script>
POST

Not used, and disabled, returns nothing.

PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

Monitor

A method to store the TickStream.KeyID measurements, but without returning an Evaluation result. This is typically used for offline analysis, auditing, or documentation applications. Most often, this method is called asynchronously, and the return value is ignored.

GET

Not used, returns a 404 response code.

POST

URI

/monitor

URI Parameters

none

Data Parameters

License
The TickStream.KeyID license code value.

EntityID
Unique identifier provided for the Profile associated with this effort. This can be any alphanumeric value.

tsData
The serialized, compressed behavior values, as returned from the populateControlWithKeyDataConcatenated function in the TickStream.KeyID jQuery library, or an equivalent.

EntityNotes
Additional information that an application may want to store along with this set of measurements.

Success Response

An empty string result indicates the method was executed successfully.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the error detail contains sensitive information, it appears in the server log, but is not transmitted to the client. Otherwise, the error will be returned as a JSON format string in the form: [{"Error": "Error message (String)"}]

Sample

given the following data submitted via POST (application/x-www-form-urlencoded)

=[{'License':'(license value)', 'EntityID':'johndoe%40anycorp.com', 'tsData':'(tsData value)', 'EntityNotes':''}]

returns

""
PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

TypingMistake

For recording typing mistakes. Usually for tracking the frequency of "typos" during an evaluation phase, but also useful for understanding the correlation between behavioral failures and the regular inability to type the given password.

GET

Not used, returns a 404 response code.

POST

URI

/typingmistake

URI Parameters

none

Data Parameters

License
The TickStream.KeyID license code value.

EntityID
Unique identifier provided for this effort, such as a username. This can be any alphanumeric value.

Mistype
The mistyped characters. This information can be encrypted and encoded in a Base64 format.

SessionID (optional)
A unique session identifier that can be used to relate multiple events.

Page (optional)
A page name that can be used for reporting on mistypes related to specific web pages.

Action (optional)
The name of the action or script on the page associated with this event.

Template (optional)
The source template used for matching (the actual password). This information can be encrypted and encoded in a Base64 format, and is further encrypted using AES256.

Success Response

An empty string result indicates the method was executed successfully.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the error detail contains sensitive information, it appears in the server log, but is not transmitted to the client. Otherwise, the error will be returned as a JSON format string in the form: [{"Error": "Error message (String)"}]

Sample

given the following data submitted via POST (application/x-www-form-urlencoded)

=[{'License':'(license value)', 'EntityID':'johndoe%40anycorp.com', 'MisType':'pasword'}]

returns

""
PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.

Validation

Provides information about current validation settings as configured on the TickStream.KeyID server, as well as methods to test a given password for both construction and extended behavior validation.

GET

URI

/validation

URI Parameters

Password (optional)
The password string value to test against the current validation settings.

Data Parameters

none

Success Response

With no URI parameter, the result will be plaintext that describes the current validation settings, relating to the construction of acceptable passwords. With a URI parameter (a password to test), the result is a JSON formatted string containing the number of messages, and the messages themselves, in three different categories: Information (INFO), Warning (WARN), and Failure (FAIL).

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client. Otherwise, the error will be returned as a JSON format string in the form: [{"Error": "Error message (String)"}]

Sample

http://keyid-services.anycorp.com/validation/mypassword

returns

{"INFOCOUNT":"1","INFO":"The text contains all or parts of 4 (4-10 letter) common words, including pass, word, sword, password.","WARNCOUNT":"2","WARN":"The text contains segments of words considered too popular, including \"password\", \"pass\". The text only contains lowercase characters. Please consider adding a mix instead."}
POST

URI

/validation

URI Parameters

none

Data Parameters

License
The TickStream.KeyID license code value.

tsData
The serialized, compressed behavior values, as returned from the populateControlWithKeyDataConcatenated function in the TickStream.KeyID jQuery library, or an equivalent.

Success Response

Returns a JSON formatted string with the results of extended construction and behavior analysis validation. This is typically used during the Profile building process to ensure the efforts are both genuine and high quality.

Error Response

All errors are logged on the server for investigation, and are accessible through the management interface. If the method returns an empty string, this indicates an error occurred, which may contain sensitive detail. The error detail appears in the server log, but is not transmitted to the client. Otherwise, the error will be returned as a JSON format string in the form: [{"Error": "Error message (String)"}]

Sample

given the following data submitted via POST (application/x-www-form-urlencoded)

=[{'License':'(license value)', 'tsData':'(tsData value)'}]

returns

[{"Statistic":"OpinionFailureCount","Value":"1"},{"Statistic":"OpinionFailureMessages","Value":"Typing speed aberation (percent of time typing string)"},{"Statistic":"OpinionInfoCount","Value":"1"},{"Statistic":"OpinionInfoMessages","Value":"Text contains all or parts of 9 (4-10 letter) common words: including pass, word, sword, password"},{"Statistic":"OpinionWarnCount","Value":"1"},{"Statistic":"OpinionWarnMessages","Value":"2 possible fast speed concerns Leading into Char #2 ("h") cps = 7.46t(Infinity above 0) Leading into Char #3 ("o") cps = 5.18t(Infinity above 0)"}]
PUT

Not used, and disabled, returns nothing.

DELETE

Not used, and disabled, returns nothing.