Table of Contents

• Introduction
• check_out_full_license

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

Introduction

Web API v3.4 is a superset of version 3.3 of the web API. It adds the ability to check out an entire license for offline use without first registering an instance. It is the latest released version. All v3.3 endpoints are available under /api/v3.4/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.

check_out_full_license

Checks out a complete license, identified by its license key, for a specified duration. The result contains a signed copy of the license details that a client (for example, a local license server or an air-gapped desktop application) can use to enforce the license while offline. No instance or user is registered. While the license is checked out, online validations against it fail with status -17.

This replaces the full_license option of check_out_license, which is no longer supported.

Endpoint

/api/v3.4/auth/check_out_full_license

Data

{
    "product_guid" : <string>,
    "license_key" : <string>,
    "version" : <string>,
    "duration" : <integer>,
    "instance_identity" : <instance_identity>
}

Note: duration is the length of the checkout in seconds. instance_identity identifies the machine that will hold the license; it is required because it is used to encrypt full_license_encrypted. If the product defines versions, version must match one of them.

Requirements:

• The product must be a desktop or web application product (otherwise status -16).
• The license must not have any enabled registered instances (otherwise status -16).
• The license must be active and not already checked out (otherwise status -2 or -17).

Value on success

{
    "status" : 0,
    "time" : <string>,
    "checkout_key" : <string>,
    "expiration_time" : <string>,
    "features" : [ <string>, <string>, ... ],
    "feature_groups" : [ <string>, <string>, ... ],
    "full_license_json" : <string>,
    "full_license_checksum" : <string>,
    "full_license_encrypted" : <string>
}

Property	Description
checkout_key	Identifies the checkout. Pass it to check_in_license to return the license early.
expiration_time	When the checkout expires, as an RFC 822 UTC timestamp.
full_license_json	A JSON-encoded string containing the license details: key, type, product, terms, restrictions, entitlements, components (for the requested version), features, feature groups, grace period, checkout_key and expiration_time.
full_license_checksum	Base64-encoded RSA-SHA256 signature of full_license_json, made with the product's private key. Verify it with the product's public key.
full_license_encrypted	full_license_json encrypted with AES-128-CBC and Base64-encoded. The key and IV are the first and second 16 bytes of the SHA-256 hash of the hardware string derived from instance_identity, so only a machine with a matching identity can decrypt it.

In version 3.5 (preview, not yet released) the result also includes custom_data.

Value on failure

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

Status -5 is returned for an unknown product, -6 for an unknown license key and -10 if the version is not found.