Table of Contents

• Introduction
• Feature groups
• get_license_info
• check_in_components

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

Introduction

Web API v3.3 is a superset of version 3.2 of the web API. It adds feature groups to session and validation results, a method for retrieving license owner and expiration information, and a method for checking in components that were checked out to a session. All v3.2 endpoints are available under /api/v3.3/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.

Feature groups

The following property is added to the results of begin_app_session, begin_user_session, validate_instance, extend_session and check_out_license:

{
    ...
    "feature_groups" : [ <string>, <string>, ... ],
    ...
}

feature_groups contains the names of the feature groups in effect for the instance (and user, when a user is known), in the same way that features contains the names of the features in effect. It is included in successful results. For validate_instance it is also included when validation fails but the instance was found.

get_license_info

Returns information about the license used by a session: the license owner's name and logo, and the license expiration date. The session is identified by its current session token. Unlike extend_session, this call does not consume or replace the token.

Endpoint

/api/v3.3/auth/get_license_info

Data

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

Value on success

{
    "status" : 0,
    "time" : <string>,
    "owner_name" : <string>,
    "owner_logo_url" : <string>,
    "expiry" : <string>
}

Note: owner_logo_url is an empty string if the license owner is not a company or has no logo. expiry is the end date of the license's current term as an RFC 822 UTC timestamp. If the license has no current term, expiry is a date in the past.

Value on failure

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

Status -1 is returned for an unknown token and -12 for a token that is no longer active or whose session has ended.

check_in_components

Checks in components that were checked out to a session with check_out_components, returning them to the pool before the session ends. (Components checked out offline with check_out_component_tokens are checked in with check_in_component_tokens instead.)

Endpoint

/api/v3.3/auth/check_in_components

Data

{
    "product_guid" : <string>,
    "session_key" : <string>,
    "components" : <string|string_array>
}

Note: components contains component names. Checking in a component that the session has already checked in has no effect and is not an error, so a check-in can safely be retried. If the session is no longer active, the call has no effect and succeeds.

Value on success

{
    "status" : 0,
    "time" : <string>,
    "components" : [ ... ],
    "component_entitlements" : [ ... ]
}

components and component_entitlements have the same format as in check_out_consumable_component and reflect the state after the check-in. They are empty if the session is no longer active.

Value on failure

{
    "status" : -1,
    "time" : <string>,
    "error" : "Invalid session"
}

If a named component does not exist, or was never checked out by the session, the server responds with HTTP 400 Bad Request. Every component in the list is still attempted: the other components are checked in even when the response is 400.