Skip to content

Borrow API Reference🔗

The Borrow API allows you to borrow licenses from the License Server for offline usage. This API follows the JSON-RPC 2.0 specification.

Server configuration🔗

The Borrow API is available at the endpoint /licenses on the License Server. The server listens on port 22022 by default.

Methods🔗

ListLicensesV1🔗

List all licenses the license server manages.

Parameters🔗

This method takes no parameters.

Result🔗

Returns an array of LicenseInfo objects.

LicenseInfo🔗

Represents detailed information about a license managed by the server.

Property Type Optional Description
feature string No Defines if the license is an SDK or Runtime license. Allowed values: MVTec_HDevelop, MVTec_HALCON
uuid string No Unique identifier of the license. Is unique in combination with the feature
version string No Version for which the license is valid
edition string No Edition of the license. Allowed values: Progress, Steady, Steady-Progress
modules string No String encoding the modules included in the license. Pattern: ^f?c?1?2?3?b?d?o?m?i?t?$
count integer No Number of licenses
validFrom date-time Yes Start date from which the license is valid. If not present, the license is valid from the beginning of time. Must be a date or date-time in ISO-8601 format.
validUntil date-time Yes End date until which the license is valid. If not present, the license does not expire. Must be a date or date-time in ISO-8601 format.
borrowedIntervals array Yes Array of BorrowedInterval objects representing current borrow periods. If the license is not borrowed, this parameter is omitted.
BorrowedInterval🔗

Represents a time interval during which a license is borrowed.

Property Type Optional Description
validFrom date-time No Start date of the borrow interval. Must be a date or date-time in ISO-8601 format.
validUntil date-time No End date of the borrow interval. Must be a date or date-time in ISO-8601 format.
hostId string No Host ID of the machine for which the license was borrowed. Must be either a MAC address in the format MAC:XXXXXXXXXXXX where X is a hexadecimal digit or a Wibu Dongle ID in the format CM:3-XXXXXXXXXX where X is a decimal digit
userInfo string Yes Optional user defined information associated with the borrowed license
borrowId string No Uniquely identifies the borrowed license

Errors🔗

Code Message Description
-32603 Internal error An internal server error occurred

Example🔗

Request:

{
  "jsonrpc": "2.0",
  "method": "ListLicensesV1",
  "params": [],
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "feature": "MVTec_HDevelop",
      "uuid": "118cf2e7b3d20001",
      "version": "26.05",
      "edition": "Progress",
      "modules": "fc123bdomit",
      "validUntil": "2026-12-31T23:59:59Z",
      "count": 1,
      "borrowedIntervals": [
        {
          "validFrom": "2025-12-01T08:00:00Z",
          "validUntil": "2025-12-01T20:00:00Z",
          "hostId": "MAC:2C549188C9E3",
          "userInfo": "Jane Doe",
          "borrowId": "934c1302-1320-42c3-a3ef-6340ff8cd2f3"
        }
      ]
    }
  ],
  "id": 1
}

BorrowLicenseV1🔗

Borrow a license specified by uuid and feature.

Parameters🔗

Name Type Required Description
feature string Yes Defines if the license is an SDK or Runtime license. Allowed values: MVTec_HDevelop, MVTec_HALCON
uuid string Yes Unique identifier of the license. Is unique in combination with the feature
hostId string Yes Host ID of the machine for which the license is borrowed. Must be either a MAC address in the format MAC:XXXXXXXXXXXX where X is a hexadecimal digit or a Wibu Dongle ID in the format CM:3-XXXXXXXXXX where X is a decimal digit
validFrom date-time No Start date of the borrow interval. If not set the current server time is used. Must be a date or date-time in ISO-8601 format.
validUntil date-time Yes End date of the borrow interval. Must be a date or date-time in ISO-8601 format.
userInfo string No Optional field to assign a user defined value to the borrowed license

Result🔗

Returns a BorrowedLicense object.

BorrowedLicense🔗

Represents a borrowed license returned by the server.

Property Type Optional Description
license string No The borrowed license
borrowId string No Uniquely identifies the borrowed license

Errors🔗

Code Message Description
-32602 Invalid params The provided parameters are invalid
-32603 Internal error An internal server error occurred
32 License not available for borrowing in the requested time interval The license is already borrowed for the requested period
33 Borrowing after license expiration not allowed The borrow period extends beyond the license expiration
34 No matching license found No license matching the uuid and feature was found
35 Invalid borrow interval The specified borrow interval is invalid
36 Invalid host id The provided host ID format is invalid

Example🔗

Request:

{
  "jsonrpc": "2.0",
  "method": "BorrowLicenseV1",
  "params": {
    "feature": "MVTec_HDevelop",
    "uuid": "118cf2e7b3d20001",
    "hostId": "MAC:2C549188C9E3",
    "validFrom": "2025-12-01T08:00:00Z",
    "validUntil": "2025-12-01T20:00:00Z",
    "userInfo": "Jane Doe"
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "license": "LICENSE MVTec_HDevelop 25.11 [...]"
  },
  "id": 1
}

GetBorrowedLicenseV1🔗

Get a previously borrowed license by its unique identifier.

Parameters🔗

Name Type Required Description
borrowId string Yes Uniquely identifies the borrowed license

Result🔗

Returns a BorrowedLicense object.

BorrowedLicense🔗

Represents a borrowed license returned by the server.

Property Type Optional Description
license string No The borrowed license

Errors🔗

Code Message Description
-32602 Invalid params The provided parameters are invalid
34 No matching license found No license matching the borrowId was found

Example🔗

Request:

{
  "jsonrpc": "2.0",
  "method": "GetBorrowedLicenseV1",
  "params": {
    "borrowId": "934c1302-1320-42c3-a3ef-6340ff8cd2f3"
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "license": "LICENSE MVTec_HDevelop 25.11 [...]"
  },
  "id": 1
}

Error Codes🔗

The API uses standard JSON-RPC 2.0 error codes as well as custom application-specific error codes.

Standard JSON-RPC Errors🔗

Code Message Description
-32602 Invalid params The provided parameters are invalid
-32603 Internal error An internal server error occurred

Application-Specific Errors🔗

Code Message Description
32 License not available for borrowing in the requested time interval The requested license is already borrowed for the specified period
33 Borrowing after license expiration not allowed Cannot borrow a license beyond its expiration date
34 No matching license found The specified license (uuid/feature combination) does not exist
35 Invalid borrow interval The borrow interval is malformed or invalid
36 Invalid host id The provided host ID format is not valid

Code Examples🔗

Basic Setup🔗

No setup required

import requests
import json

BASE_URL = "https://localhost:22022/licenses"
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json"
}

def call_api(method: str, params: dict | list = None, request_id: int = 1) -> dict:
    """
    Make a JSON-RPC call to the Borrow API.

    Args:
        method: The API method to call
        params: Parameters to pass to the method
        request_id: Unique request identifier

    Returns:
        The JSON response as a dictionary
    """
    payload = {
        "jsonrpc": "2.0",
        "method": method,
        "params": params if params is not None else [],
        "id": request_id
    }

    response = requests.post(BASE_URL, headers=HEADERS, json=payload)
    response.raise_for_status()
    return response.json()

List All Licenses🔗

curl -X POST https://localhost:22022/licenses \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "ListLicensesV1",
    "params": [],
    "id": 1
  }'

def list_licenses() -> list:
    """Retrieve all licenses from the server."""
    response = call_api("ListLicensesV1")

    if "error" in response:
        raise Exception(f"API Error: {response['error']['message']}")

    return response["result"]

# Usage
licenses = list_licenses()
for license in licenses:
    print(f"License: {license['feature']} - {license['uuid']}")
    print(f"  Edition: {license['edition']}, Version: {license['version']}")
    if license.get('borrowedIntervals'):
        print(f"  Borrowed intervals: {len(license['borrowedIntervals'])}")

Borrow a License🔗

curl -X POST https://localhost:22022/licenses \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "BorrowLicenseV1",
    "params": {
      "feature": "MVTec_HDevelop",
      "uuid": "118cf2e7b3d20001",
      "hostId": "MAC:2C549188C9E3",
      "validFrom": "2025-12-01T08:00:00Z",
      "validUntil": "2025-12-01T20:00:00Z",
      "userInfo": "Jane Doe"
    },
    "id": 2
  }'

from datetime import datetime, timedelta

def borrow_license(
    feature: str,
    uuid: str,
    host_id: str,
    valid_from: datetime,
    valid_until: datetime,
    user_info: str = None
) -> str:
    """
    Borrow a license for offline usage.

    Args:
        feature: License feature type (MVTec_HDevelop or MVTec_HALCON)
        uuid: Unique identifier of the license
        host_id: Host ID of the target machine
        valid_from: Start of the borrow period
        valid_until: End of the borrow period
        user_info: Optional user information

    Returns:
        The license string
    """
    params = {
        "feature": feature,
        "uuid": uuid,
        "hostId": host_id,
        "validFrom": valid_from.strftime("%Y-%m-%dT%H:%M:%SZ"),
        "validUntil": valid_until.strftime("%Y-%m-%dT%H:%M:%SZ")
    }

    if user_info:
        params["userInfo"] = user_info

    response = call_api("BorrowLicenseV1", params)

    if "error" in response:
        error = response["error"]
        raise Exception(f"API Error {error['code']}: {error['message']}")

    return response["result"]["license"]

# Usage
now = datetime.utcnow()
license_data = borrow_license(
    feature="MVTec_HDevelop",
    uuid="118cf2e7b3d20001",
    host_id="MAC:2C549188C9E3",
    valid_from=now,
    valid_until=now + timedelta(hours=12),
    user_info="Jane Doe"
)
print(f"Borrowed license: {license_data[:50]}...")

Get a Borrowed License🔗

curl -X POST https://localhost:22022/licenses \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "GetBorrowedLicenseV1",
    "params": {
      "borrowId": "934c1302-1320-42c3-a3ef-6340ff8cd2f3"
    },
    "id": 3
  }'

def get_borrowed_license(borrow_id: str) -> str:
    """
    Retrieve a previously borrowed license.

    Args:
        borrow_id: The unique identifier of the borrowed license

    Returns:
        The license string
    """
    params = {"borrowId": borrow_id}
    response = call_api("GetBorrowedLicenseV1", params)

    if "error" in response:
        error = response["error"]
        raise Exception(f"API Error {error['code']}: {error['message']}")

    return response["result"]["license"]

# Usage
license_data = get_borrowed_license("934c1302-1320-42c3-a3ef-6340ff8cd2f3")
print(f"Retrieved license: {license_data[:50]}...")