Table of Contents

Calling conventions

All API v3 endpoints accept JSON data with the following schema:

{
    "key" : <string>,
    "data" : <string>
}
Parameter Description
key An API key that allows the server to decrypt the data parameter value
data An encrypted version of the actual data supplied to the API endpoint

Instance Identity Data Format

A number of the API endpoints accept an instance_identity parameter. The value specified for that parameter must take the following form:

"instance_identity" : {
    "key1" : <key_value>,
    "key2" : <key_value>,
    "_version" : <number>,
    "_max_mismatch_count" : <number>,
    ...
}
where <key_value> is one of: 
<string>
<string_array>
{ "value" : <string> }
{ "value" : <string_array> }
If the block form of <key_value> is used, the following keys can be added to control how the server matches the value against a previously-registered value: 
{
    "_weight" : <number>,
    "_case_sensitive" : <true/false>,
    "_max_array_values_removed" : <number>
}

Keys that do not begin with an underscore (_) are regular keys. These regular key/value pairs are compared directly by the instance matching algorithm to determine if two instance identities are considered a match. Keys that begin with an underscore (_) are known as behavior keys and are not used directly in instance identity comparisons. Instead, they affect the behavior of the matching algorithm and the strictness with which the matchin algorithm behaves. All behavior keys are optional.

Behavior Key Description Default
_version An arbitrary version number used by clients to identify to the version of the matching behavior being specified in the instance identity. This is typically changed when new keys are added or old keys are removed from the identity. 1
_max_mismatch_count Specifies the maximum number of key/value pairs that can be different between two instance identities while still considering them a match. If there are more different key/value pairs than this value, the two identities do not match. 1
_weight An integer value specifying the weight of this key relative to other keys. Setting this to zero effectively tells the server to ignore this key. Setting it to 2 tells the server to consider a mismatch of this key as equivalent to two mismatches overall. 1
_case_sensitive Whether values use case-sensitive comparison. true
_max_array_values_removed Array values only. When comparing two instance identities, this value specifies the maximum number of values that can be removed from the array in the second instance to still be considered a match with the first instance. 1

register_instance

Registers a product instance with the server. If an instance with the same instance identity already exists, that instance is returned.

Endpoint

/api/v3/auth/register_instance

Data

{
    "product_guid" : <string>,
    "license_key" : <string>,
    "instance_identity" : <instance_identity>
}

Value on success

{
    "success" : true
    "time" : <string>,
    "instance_guid" : <string>,
    "validation_grace_period" : <number>
    "first_registered_at" : <string>
}

Value on failure

{
    "success" : false,
    "time" : <string>,
    "error" : <string>
}

validate_instance

Validates a product instance. The product instance is identified by its instance id. Instances registered via register_app cannot call this method.

Endpoint

/api/v3/auth/validate_instance

Data

{
    "product_guid" : <string>,
    "instance_guid" : <string>,
    "version" : <string>,
    "instance_identity" : <instance_identity>
}

Note: The instance_identity parameter is optional. When present, it is used to verify that the instance's current identity matches the identity when the instance was registered. It is highly recommended to include this information if your users have control over any of the information which defines the identity (hardware, for example).

Value on success

{
    "status" : <number>,
    "time" : <string>,
    "features" : [ <string>, <string>, <string>, ... ],
    "validation_grace_period" : <number>
}

Value on failure

{
    "success" : false,
    "time" : <string>,
    "error" : <string>
}

register_user

Registers a user of a product instance with the server. If a user with the same user profile already exists, that user is returned.

Endpoint

/api/v3/auth/register_user

Data

{
    "product_guid" : <string>,
    "instance_guid" : <string>,
    "user_info" : {
        "name" : <string>,
        "email" : <string>
    },
    "user_identity" : {
        "key1" : "value1",
        "key2" : "value2",
        ...
    }
}

Value on success

{
    "success" : true
    "time" : <string>,
    "user_guid" : <string>,
    "session_duration" : <number>,
    "validation_grace_period" : <number>
    "first_registered_at" : <string>
}

Value on failure

{
    "success" : false,
    "time" : <string>,
    "error" : <string>
}

register_app

Registers a product instance and its associated user with the server. If an instance with the same identity and user combination already exists, that instance is returned.

Endpoint

/api/v3/auth/register_app

Data

{
    "product_guid" : <string>,
    "license_key" : <string>,
    "instance_identity" : <instance_identity>,
    "user_info" : {
      "name" : <string>,
      "email" : <string>
    },
    "user_identity" : {
      "key1" : "value1",
      "key2" : "value2",
      ...
    }
}

Value on success

{
    "success" : true
    "time" : <string>,
    "instance_guid" : <string>,
    "user_guid" : <string>,
    "session_duration" : <number>,
    "validation_grace_period" : <number>
    "first_registered_at" : <string>
}

Value on failure

{
    "success" : false,
    "time" : <string>,
    "error" : <string>
}

begin_user_session

Begins a new session of a user of a product instance. The product instance is identified by its instance id and the user is identified by its user id. Instances and users registered via register_app cannot call this method.

Endpoint

/api/v3/auth/begin_user_session

Data

{
    "product_guid" : <string>,
    "instance_guid" : <string>,
    "user_guid" : <string>,
    "user_identity" : {
        "key1" : "value1",
        "key2" : "value2",
        ...
    },
    "duration" : <number>
}

Note: The user_identity parameter is optional. When present, it is used to verify that the user's current information matches the information when the user was registered. It is highly recommended to include this information if the user_hash value is generated from data that the user can affect (e.g. Active Directory credentials).

Note: The duration parameter is optional. When present, the server may or may not respect the value, depending on the configuration of the license.

Value on success

{
    "status" : <number>,
    "time" : <string>,
    "session_key" : <string>,
    "token" : <string>,
    "features" : [ <string>, <string>, <string>, ... ],
    "session_duration" : <number>,
    "validation_grace_period" : <number>
}

Value on failure

{
    "success" : false,
    "time" : <string>,
    "error" : <string>
}

begin_app_session

Begins a new session for both a user and a product instance. The product instance is identified by its instance id. Instances must have been registered via register_app to call this method.

Endpoint

/api/v3/auth/begin_app_session

Data

{
    "product_guid" : <string>,
    "instance_guid" : <string>,
    "user_guid" : <string>,
    "version" : <string>,
    "instance_identity" : <instance_identity>,
    "user_identity" : {
        "key1" : "value1",
        "key2" : "value2",
        ...
    },
    "duration" : <number>
}

Note: The user_guid parameter is required except when called from clients that registered using v1 or v2 of the client API.

Note: The instance_identity parameter is optional. When present, it is used to verify that the instance's current identity matches the identity when the instance was registered. It is highly recommended to include this information if your users have control over any of the information which defines the identity (hardware, for example).

Note: The user_identity parameter is optional. When present, it is used to verify that the user's current information matches the information when the user was registered. It is highly recommended to include this information if the user_hash value is generated from data that the user can affect (e.g. Active Directory credentials).

Note: The duration parameter is optional. When present, the server may or may not respect the value, depending on the configuration of the license.

Value on success

{
    "status" : <number>,
    "time" : <string>,
    "session_key" : <string>,
    "token" : <string>,
    "features" : [ <string>, <string>, <string>, ... ],
    "session_duration" : <number>,
    "validation_grace_period" : <number>
}

Value on failure

{
    "success" : false,
    "time" : <string>,
    "error" : <string>
}

extend_session

Extends a session.

Endpoint

/api/v3/auth/extend_session

Data

{
    "product_guid" : <string>,
    "token" : <string>,
    "duration" : <number>
}

Note: The duration parameter is optional. When present, the server may or may not respect the value, depending on the configuration of the license.

Value on success

{
    "status" : <number>,
    "time" : <string>,
    "token" : <string>,
    "features" : [ <string>, <string>, <string>, ... ],
    "session_duration" : <number>,
    "validation_grace_period" : <number>
}

Value on failure

{
    "success" : false,
    "time" : <string>,
    "error" : <string>
}

end_session

Ends a session. Ending a session is optional and is primarily used to ensure that a session cannot be extended in future calls.

Endpoint

/api/v3/auth/end_session

Data

{
    "product_guid" : <string>,
    "token" : <string>
}

Value on success

{
    "time" : <string>
}

Value on failure

Http error: 422 Unprocessable Entity