License Key Structure (Full)

The license key structure is used in Partner API 3.0 to hold the information about a license key.

Notes:

  • In the tables below, an omitted field means that the field was absent (omitted) in an incoming HTTP request: It was not present with either null nor with any other value.
  • Fields with the null value (also called null-valued fields) are fields that are present in incoming HTTP requests, but they have a null value.
  • Handling of omitted and null-valued fields by Partner API 3.0 differs from the server side perspective (for details see the tables with field descriptions below). It is necessary to take this into account in order to properly implement integration with Partner API 3.0.

  

License key structure consists of the following fields:

Field Name Field Type Description Interpretation on Input Interpretation on Output

ownerId

JSON string

An ID of a license owner.

You can obtain the ID in Plesk Partner Central: go to the Accounts tab > click the customer's name > the Internal ID field.

Required in two cases:

  • Creating a license key under the reseller account in Partner API
  • Moving a license key to another customer (under the reseller account in Partner API)

May be omitted in other cases.

The null value is treated as an error.

Always not null. Holds the ID of a key owner.

keyIdentifiers

"Key identifiers" structure (described further in this section)

The identifier of a license key.

  • If omitted, no actions.
  • If null, an error occurs.
  • If specified as a non-null value:
    • When the key is created:
      • It is expected that all subfields ("keyId", "keyNumber", and "activationCode") are omitted.
      • Otherwise, an error occurs.
    • When the key is modified:
      • It is expected that at least one subfield ("keyId", "keyNumber", or "activationCode") is specified. The specified subfield will then be checked against the values stored in the key to avoid calling a Partner API 3.0 method for the wrong license key.
      • If no subfields were specified, an error occurs.

Always not null. Holds the identifiers of a current license key.

parentKeyIdentifiers

"Key identifiers" structure (described further in this section)

The identifier of a parent license key.

  • If omitted, no actions.
  • If null, then a current license key will be detached from the parent key (if there is any).
  • Otherwise:
    • It is expected that at least one subfield ("keyId", "keyNumber", or "activationCode") is specified. A key matching the values in "keyId", "keyNumber", and "activationCode" subfields will be found. The current key will be (re-)attached to the found key.
    • If no subfields specified, an error occurs.

Null if there is no parent key for this key. Otherwise holds the identifier of a parent key.

childKeyIdentifiers

Array of "Key identifiers" structures

(described further in this section)

Each array element corresponds to a child license key.

This is an informational field. Ignored on input.

Always not null. If a license key does not have child keys, this field holds an empty array.

overridingKeyIdentifiers

"Key identifiers" structure

(described further in this section)

The identifier of the key that overrides the current key.

This is an informational field. Ignored on input.

Null if there is no key that overrides this key. Otherwise holds the identifier of the overriding key.

activationInfo

"Key activation info" structure (described further in this section)

Information about activation of a license key.

Note: The key activation function is not supported in modern Plesk versions and is kept for backward compatibility.

  • If omitted, no actions.
  • If null:
    • If a key does not support activation, no actions.
    • If a key supports activation, an error occurs.
  • If specified:
    • If a key does not support activation, an error occurs.
    • If a key supports activation:
      • If the uid subfield is omitted, no actions.
      • If the uid subfield is present, then the key with the specified UID is activated (re-activated, deactivated).

Null if a license key does not support activation. Otherwise non-null "key activation info" structure.

ipAddressBinding

JSON string

The IP address that a license key is bound to. Can be both IPv4 and IPv6.

  • If omitted, no actions.
  • If null, a license key is unbound from the IP address to which it was bound.
  • Otherwise, (re-)bind a license key to the specified IP address.

The IP address to which the license key is bound. If no IP address is associated with a license key, the null value is returned.

restrictIPBinding

JSON boolean

Specifies whether a license key can (false) or cannot (true) be used on IP addresses other than ipAddressBinding.

May be omitted.

If this parameter is omitted on key creation, the value is set according to the account settings - the Default IP Binding.

Always not null.

productConfigurationId

JSON number

Product configuration ID.

  • On license key creation:
    • If omitted or null, default product configuration will be associated with the license key (if applicable).
    • If not null:
      • If the specified product configuration is not supported for the license key, an error occurs.
      • Otherwise, the specified product configuration will be associated with the license key.
  • On license key modification:
    • If omitted, no actions.
    • If null:
      • If the specified product configuration is not supported for a license key, no actions.
      • Otherwise, an error occurs.
    • If not null:
      • If the product configuration is not supported for a license key, an error occurs.
      • Otherwise, the specified product configuration will be associated with a license key.

Always not null for license keys that support product configurations.

Null for license keys that do not support product configurations.

nickname

JSON string

The text information about a license key (such as alias, custom tag, and so on).

If the null value or empty string was specified, the value is reset to an empty string ("").

Otherwise, the information about a license key is updated with the specified value.

A non-null value of the description. By default, each license has an empty ("") description.

items

Array of "Key item (key billable component)" structures (described further in this section)

The items (billable components) of a license key.

Required for license key creation.

May be omitted in the key modification command. However, if specified, it must have at least one element in the array.

The null value leads to an error.

A non-empty array of key items (billable components).

creationDate

JSON string with timestamp in ISO 8601 format

License creation date and time.

This is an informational field. Ignored on input.

Always not null.

lastModificationDate

JSON string with timestamp in ISO 8601 format

License last modification date.

This is an informational field. Ignored on input.

Always not null.

updateDate

JSON string with timestamp in ISO 8601 format

The date when a license key should be updated the next time.

This is an informational field. Ignored on input.

Always not null.

expirationDate

JSON string with timestamp in ISO 8601 format

The date when a license key becomes expired if it was not updated.

This is an informational field. Ignored on input.

Always not null.

susExpirationDate

JSON string with timestamp in ISO 8601 format

The date when SUS becomes expired if it would not be renewed.

This is an informational field. Ignored on input.

Null for licenses without SUS.

susStatus

JSON string  with possible values 'ACTIVE', 'EXPIRED'

The SUS status.

This is an informational field. Ignored on input.

Null for licenses without SUS.

supportExpirationDate

JSON string with timestamp in ISO 8601 format

The date when support becomes expired.

This is an informational field. Ignored on input.

Null for licenses without support.

supportStatus

JSON string  with possible values 'ACTIVE', 'EXPIRED'

The support status.

This is an informational field. Ignored on input.

Null for licenses without support.

autoRenew

JSON boolean

Specifies whether a license key is renewed automatically by Key Administrator.

May be omitted. If present and applicable (a license key is of the Lease or Long Lease type), then the key's autoRenew flag will be changed to the specified value.


If this parameter is omitted on key creation, the value is set according to the account settings - Default value for Auto-renewal for long-term lease licenses (1 Year and longer), Default value for Auto-renewal for regular lease licenses.

Non-null for lease or long lease,
true for purchased keys,
null otherwise.

terminated

JSON boolean

Specifies whether a license key is terminated.

May be omitted. If present, then a license key will be terminated depending on the value of this field (true or false respectively).

The null value leads to an error.

Always not null.

suspended

JSON boolean

Specifies whether a license key is suspended.

May be omitted. If present, then key will be suspended or resumed depending on the value of this field (true or false respectively).

The null value leads to an error.

Always not null.

status

JSON string  with possible valies 'ACTIVE', 'EXPIRED', 'TERMINATED', 'SUSPENDED'

Specifies a license key status.

This is an informational field. Ignored on input.

Always not null.

ownerSuspended

JSON boolean

Specifies whether a license key is suspended because its owner is also suspended.

This is an informational field. Ignored on input.

Always not null.

fraud

JSON string

Specifies whether a license is detected as being used on multiple Plesk servers.

This is an informational field. Ignored on input. The only available value: multiuse.

The only available value: multiuse.

The Key Identifiers Structure

The Key identifiers structure encapsulates identifier fields that are unique for a license key and can be used in Key Administrator or Partner Central to address a license key:

Field Name Field Type Description Interpretation on Input Interpretation on Output

keyId

JSON number

License key number without prefix and version

Ignored if omitted. Otherwise the specified value is checked against the actual number of a key to avoid invocation of Partner API 3.0 method with the wrong key.

The null value leads to an error.

Always not null. Note that this field can be used for addressing a license key via URL. For example: https://api.central.plesk.com/30/keys/12345678

keyNumber

JSON string

Full notation of a license key number (with prefix and version)

Ignored if omitted. Otherwise the specified value is checked against the actual number of a key to avoid invocation of a Partner API 3.0 method with the wrong key.

The null value leads to an error.

Always not null. This field cannot be used for addressing a license key via URL.

activationCode

JSON string

Activation code (if any)

Ignored if omitted. Otherwise the specified value is checked against the actual activation code of a key to avoid invocation of a Partner API 3.0 method with the wrong key.

The null value is OK if a license key does not have an activation code. Otherwise, the null value leads to an error.

The null value if a license key does not have activation code. Also, null if a license key belongs to a different owner than the current key. Note that this field can be used for addressing a license key by URL. For example: https://api.central.plesk.com/30/keys/A99W00-TRMC02-Y1WR36-K8JJ70-0BWR01

The Key Activation Info Structure

The Key activation info (activationInfo) structure holds information about activation of license key:

Field Name Field Type Description Interpretation on Input Interpretation on Output

activated

JSON boolean

Specifies whether this license key is already active (for example, when UID is optional) or activated (when UID is mandatory and a license was already activated).

This is an informational field. Completely ignored on input.

Always not null.

uid

JSON string

The UID used for activation.

If omitted, no actions.

If present:

  • If null, a license will be deactivated.
  • If not null, a license will be (re-)activated with the specified value.

Null if no UID is currently assigned to a license key, otherwise - a non-null UID value.

Note: The key activation function is not supported in modern Plesk versions and is kept for backward compatibility.

The Key Item Structure

The Key item (key billable component) (item) is an auxiliary structure that holds information about a separate billable part of a license subscription:

Field Name Field Type Description Interpretation on Input Interpretation on Output

externalId

JSON string

The ID of a billable key component. This ID is external with respect to Key Administrator and Partner Central and is assigned to a license by a billing system.

If omitted, the value of this field is treated as null. The value will be stored on Key Administrator and Partner Central side.

The null value is permitted.

The exact value stored on Key Administrator and Partner Central side is returned. May be null, if null is stored.

item

JSON string

One of the following:

One of the following:

  • A Partner API 3.0 constant name.
  • Key type (base license name) or feature name for unmatched items.

Must not be omitted, null-valued, or empty (with no elements).

One of the following:

  • A Partner API 3.0 constant name.
  • Key type (base license name) or feature name for unmatched items.
Example

The license key for Plesk 12 with unlimited domains, 5 language packs, and an additional key for MagicSpam might have the following structure:

{
  "ownerId" : "123123123",
  "keyIdentifiers" : {
    "keyId" : 1234567,
    "keyNumber" : "PLSK.01234567.0002",
    "activationCode" : "AAAAAA-BBBBBB-CCCCCC-DDDDDD-EEEEEE"
  },
  "parentKeyIdentifiers" : null,
  "activationInfo" : null,
  "ipAddressBinding" : null,
  "nickname" : "",
  "productConfigurationId" : 13132341,
  "items" : [ {
    "externalId" : null,
    "item" : "PLESK-12-WEB-ADMIN-1M"
  }, {
    "externalId" : null,
    "item" : "FT-PLESK-5-LANGUAGE-PACKS-1M"
  } ],
  "creationDate" : "2015-08-24T07:31:21.057Z",
  "lastModificationDate" : "2015-08-24T07:40:01.232Z",
  "updateDate" : "2015-09-24T00:00:00.000Z",
  "expirationDate" : "2015-10-04T00:00:00.000Z",
  "susExpirationDate" : "2015-10-04T00:00:00.000Z",
  "susStatus" : "ACTIVE",
  "supportExpirationDate" : null,
  "supportStatus" : null,
  "status" : "ACTIVE",
  "terminated" : false,
  "suspended" : false,
  "ownerSuspended" : false,
  "autoRenew" : false,
  "restrictIPBinding" : false,
  "childKeyIdentifiers" : [ {
    "keyId" : 1234568,
    "keyNumber" : "MSP.01234568.0000",
    "activationCode" : null
  } ]
}?

   

 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.