Licensing Operations Import License

Licensing Operations Import License
Import a signed license file

Imports a signed license file. A file for a serial number that is already installed replaces that license, in any state, and the answer is 200; a new serial number is installed and the answer is 201. A file with fewer cores or an earlier validTo than the installed one is not installed until the call is repeated with confirmDowngrade=true; the first call answers 409 LICENSE_UPDATE_REQUIRED_CONFIRMATION with the comparison and the resulting pool. The request body is the license file as text/plain, which is Base64 text that decodes to a 256-byte signature followed by the signed XML. The body must be valid UTF-8 and at most 65536 bytes (64 KB, counted in bytes). An empty, larger or non-UTF-8 body is rejected with 400 LICENSE_FORMAT_INVALID. A file whose format, certificate chain, signature, product, serial number, validity dates or cores are not valid is rejected with 400 and a stable license error code, and a license whose serial number or file is already installed is rejected with 409 LICENSE_DUPLICATE. ADMIN only.

Request
URI
POST
https://{api_host}/api/v1/licensing/licenses
COPY
Query Parameters
boolean
confirmDowngrade
Optional
Constraints: default: false

Set to true to install a file that lowers the cores or the validTo of the installed license of the same serial number. Without it such a file is refused with 409 LICENSE_UPDATE_REQUIRED_CONFIRMATION.

confirmDowngrade example
true

Request Body

The signed license file as text/plain: Base64 text that decodes to a 256-byte signature followed by the signed XML. It must be valid UTF-8 and at most 65536 bytes.

"<Base64 text of the signed license file>"
Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The serial number was already installed and its license was replaced; previous holds the replaced term

Returns ImportLicenseResultDto of type(s) application/json
{
    "license": {
        "serialNumber": "0000740016",
        "product": "ESG-VCFHA-SUB",
        "validFrom": "2026-01-01",
        "validTo": "2026-02-28",
        "cores": 64,
        "status": "ACTIVE",
        "contributionCores": 64,
        "importedAt": "2026-01-15T09:00:00Z",
        "importedBy": "1",
        "deletable": false
    },
    "summary": {
        "state": "ACTIVE",
        "restricted": false,
        "overCapacity": false,
        "validLicenseCount": 1,
        "entitledCores": 64,
        "consumedCores": 48,
        "availableCores": 16,
        "overageCores": 0,
        "registeredAgents": 2,
        "onlineAgents": 1,
        "offlineAgents": 1,
        "consumingHosts": 2,
        "reclaimedHosts": 0,
        "hostsWithUnknownTopology": 0,
        "inactiveAgentDays": 14,
        "nextExpiry": {
            "serialNumber": "0000740016",
            "validTo": "2026-02-28",
            "daysLeft": 44
        },
        "lastExpiry": {
            "serialNumber": "0000740016",
            "validTo": "2026-02-28",
            "daysLeft": 44
        },
        "graceEndsAt": "2026-03-08T00:00:00Z",
        "evaluatedAt": "2026-01-15T09:30:00Z",
        "inventoryObservedAt": "2026-01-15T09:29:30Z"
    },
    "action": "UPDATED",
    "previous": {
        "cores": 32,
        "validFrom": "2026-01-01",
        "validTo": "2026-01-31"
    }
}
object
license
Required  

One installed license

object
summary
Required  

Pooled entitlement, measured consumption and state. restricted is true for NO_LICENSE and RESTRICTED

string
action
Required  

What an accepted import did

  • INSTALLED: The serial number was not installed before; the license was stored as a new one
  • UPDATED: The serial number was already installed; its file, cores and dates were replaced
Enumeration: INSTALLED, UPDATED
object
previous
Optional

The term that was replaced when action is UPDATED; null for a new install


201

201 Created successful response envelope. The result of the import, naming the installed license

Returns ImportLicenseResultDto of type(s) application/json
{
    "license": {
        "serialNumber": "0000740016",
        "product": "ESG-VCFHA-SUB",
        "validFrom": "2026-01-01",
        "validTo": "2026-02-28",
        "cores": 64,
        "status": "ACTIVE",
        "contributionCores": 64,
        "importedAt": "2026-01-15T09:00:00Z",
        "importedBy": "1",
        "deletable": false
    },
    "summary": {
        "state": "ACTIVE",
        "restricted": false,
        "overCapacity": false,
        "validLicenseCount": 1,
        "entitledCores": 64,
        "consumedCores": 48,
        "availableCores": 16,
        "overageCores": 0,
        "registeredAgents": 2,
        "onlineAgents": 1,
        "offlineAgents": 1,
        "consumingHosts": 2,
        "reclaimedHosts": 0,
        "hostsWithUnknownTopology": 0,
        "inactiveAgentDays": 14,
        "nextExpiry": {
            "serialNumber": "0000740016",
            "validTo": "2026-02-28",
            "daysLeft": 44
        },
        "lastExpiry": {
            "serialNumber": "0000740016",
            "validTo": "2026-02-28",
            "daysLeft": 44
        },
        "graceEndsAt": "2026-03-08T00:00:00Z",
        "evaluatedAt": "2026-01-15T09:30:00Z",
        "inventoryObservedAt": "2026-01-15T09:29:30Z"
    },
    "action": "INSTALLED",
    "previous": null
}
object
license
Required  

One installed license

object
summary
Required  

Pooled entitlement, measured consumption and state. restricted is true for NO_LICENSE and RESTRICTED

string
action
Required  

What an accepted import did

  • INSTALLED: The serial number was not installed before; the license was stored as a new one
  • UPDATED: The serial number was already installed; its file, cores and dates were replaced
Enumeration: INSTALLED, UPDATED
object
previous
Optional

The term that was replaced when action is UPDATED; null for a new install


400

400 Bad Request: LICENSE_FORMAT_INVALID when the body is empty, larger than 64 KB, not valid UTF-8 or not a license file in the expected format; LICENSE_CHAIN_INVALID or LICENSE_SIGNATURE_INVALID when the certificate chain or the signature does not verify; LICENSE_PRODUCT_MISMATCH when the license is for another product; LICENSE_SERIAL_INVALID, LICENSE_DATES_INVALID or LICENSE_CORES_INVALID when the serial number, the validity dates or the entitled cores are not valid; LICENSE_EXPIRED when the validity of the license file has already ended

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: FORBIDDEN when the signed-in role is not allowed to call this operation; CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


409

409 Conflict: LICENSE_DUPLICATE when the same file is already installed or the file is stored under another serial number; LICENSE_UPDATE_REQUIRED_CONFIRMATION when the file would lower the cores or the validTo of the installed license of the same serial number (nothing is changed; repeat with confirmDowngrade=true)

Operation doesn't return any data structure

500

500 Internal Server Error: INTERNAL_ERROR when the server fails unexpectedly; the message carries no detail

Returns InternalError of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: text/plain' -d '[{}]' https://{api_host}/api/v1/licensing/licenses