Table of Contents

• Introduction
• Custom data
• validate_user
• Endpoint summary

Other versions: 1.0 · 2.0 · 3.0 · 3.1 · 3.2 · 3.3 · 3.4 · 3.5 (preview)

Introduction

Web API v3.5 is a superset of version 3.4 of the web API. It is a preview and has not been released. It returns the license's custom data (key/value license properties) with successful session and validation results, and adds a method that lets a server check whether a user is still entitled to a product without starting a session. All v3.4 endpoints are available under /api/v3.5/auth/, including check_out_webapi_components.

Calling conventions, encryption and status codes are the same as in version 3.0. As in v3.2, every request must include product_guid in its data, otherwise the server responds with 400 Bad Request.

Custom data

The following property is added to successful results (status is 0) of begin_app_session, begin_user_session, validate_instance, extend_session, check_out_license, check_out_full_license and validate_user:

{
    ...
    "custom_data" : {
        "key1" : <string>,
        "key2" : <string>,
        ...
    },
    ...
}

custom_data contains the custom properties configured on the license, as an object mapping each property key to its value. Keys contain only letters, digits, underscores, hyphens and dots; values are strings (or null if no value is set). The object is empty if the license has no custom properties. Because custom properties may hold sensitive values, they are never included in failed results.

validate_user

Checks whether a registered user, on a registered instance, is currently entitled to use the product. It is intended for servers (for example, a SaaS application) that act on behalf of their users without holding a session for each of them. This is a status check, not a session start: it issues no token, does not use a seat, and does not check instance or user identity. The validation is recorded like any other validation.

Endpoint

/api/v3.5/auth/validate_user

Data

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

Value on success

{
    "status" : 0,
    "time" : <string>,
    "features" : [ <string>, <string>, ... ],
    "feature_groups" : [ <string>, <string>, ... ],
    "custom_data" : { ... }
}

features and feature_groups are those in effect for the given instance and user.

Value on failure

{
    "status" : <non-zero number>,
    "time" : <string>,
    "error" : <string>
}

Typical failure statuses:

Status	Reason
-5	Unknown product.
-1	The product is a Web API product, which cannot be validated.
-8	Unknown instance, or the instance belongs to a different product.
-2, -17	The license has expired or is fully checked out.
-4, -13, -18	The instance is disabled, pending activation, or checked out.
-7	Unknown user.
-9	The user is not registered to the instance.
-3, -2	The user is disabled, or the user's temporary access has expired.

Endpoint summary

All client licensing endpoints available in v3.5 (preview), each called with POST /api/v3.5/auth/<method>:

Method	Introduced in
register_instance	3.0
validate_instance	3.0
register_user	3.0
register_app	3.0
begin_user_session	3.0 (changed in 3.2)
begin_app_session	3.0 (changed in 3.1)
extend_session	3.0
end_session	3.0
current_release	3.0
check_out_components	3.1
components_status	3.1
check_out_license	3.2
check_in_license	3.2
check_out_component_tokens	3.2
check_in_component_tokens	3.2
get_user_license	3.2
check_out_consumable_component	3.2
check_out_webapi_components (API token, unencrypted)	3.2
get_license_info	3.3
check_in_components	3.3
check_out_full_license	3.4
validate_user	3.5