Link

Licensee Services

Licensees list

Return a list of all licensees for the current vendor.

HTTP Method / URL

GET /core/v2/rest/licensee

Security
  • Basic Authentication
  • API Key Identification
    • ROLE_APIKEY_ADMIN
    • ROLE_APIKEY_MAINTENANCE
    • ROLE_APIKEY_OPERATION
    • ROLE_APIKEY_ANALYTICS

Request Header

Accept: application/json | application/xml

Request Parameters

 - None -

HTTP Status Code

200 - Successful request
400 - Malformed or illegal request
403 - Access is denied
404 - Resource not found
500 - Internal service error

See also JavaDoc: LicenseeService.list

Example

Request

GET https://go.netlicensing.io/core/v2/rest/licensee
Accept: application/xml

Response

<netlicensing xmlns="http://netlicensing.labs64.com/schema/context">
    <items>
        <item type="Licensee">
            <property name="number">I001</property>
            <property name="active">true</property>
            <property name="CustomProperty">CustomPropertyValue</property>
        </item>
    </items>
</netlicensing>

Get licensee

Return a licensee by licenseeNumber.

HTTP Method / URL

GET /core/v2/rest/licensee/{licenseeNumber}

Security
  • Basic Authentication
  • API Key Identification
    • ROLE_APIKEY_ADMIN
    • ROLE_APIKEY_MAINTENANCE
    • ROLE_APIKEY_OPERATION
    • ROLE_APIKEY_ANALYTICS

Request Header

Accept: application/json | application/xml

Request Parameters

licenseeNumber (string) - Licensee number.

HTTP Status Code

200 - Successful request
400 - Malformed or illegal request
403 - Access is denied
404 - Resource not found
500 - Internal service error

See also JavaDoc: LicenseeService.get

Example

Request

GET https://go.netlicensing.io/core/v2/rest/licensee/I001
Accept: application/xml

Response

<netlicensing xmlns="http://netlicensing.labs64.com/schema/context">
    <items>
        <item type="Licensee">
            <property name="number">I001</property>
            <property name="active">true</property>
            <property name="CustomProperty">CustomPropertyValue</property>
        </item>
    </items>
</netlicensing>

Create licensee

Creates a new licensee.

HTTP Method / URL

POST /core/v2/rest/licensee

Security

Request Header

Accept: application/json | application/xml
Content-Type: application/x-www-form-urlencoded

Request Parameters

productNumber (string) - productNumber to assign new licensee object.

number (string) - Unique number (across all products of a vendor) that identifies the licensee. Vendor can assign this number when creating a licensee or let NetLicensing generate one. Read-only after creation of the first license for the licensee. Optional.

active (boolean) - If set to false, the licensee is disabled. Licensee can not obtain new licenses, and validation is disabled (tbd).

name (string) - Licensee name. Optional.

licenseeSecret (string) - Licensee Secret for this licensee ((info) available in selected pricing plans). Optional. (warning) Deprecated, use Node-Locked Licensing Model instead.

markedForTransfer (boolean) - Mark licensee for transfer. Optional.

HTTP Status Code

200 - Successful request
400 - Malformed or illegal request
402 - Not allowed within your pricing plan
403 - Access is denied
404 - Resource not found
500 - Internal service error

See also JavaDoc: LicenseeService.create

Example

Request

POST https://go.netlicensing.io/core/v2/rest/licensee
productNumber=PQVJQ5F7H&number=I762LBSSX&active=false
Accept: application/xml
Content-Type: application/x-www-form-urlencoded

Response

<netlicensing xmlns="http://netlicensing.labs64.com/schema/context">
    <items>
        <item type="Licensee">
            <property name="number">I762LBSSX</property>
            <property name="active">false</property>
            <property name="productNumber">PQVJQ5F7H</property>
        </item>
    </items>
</netlicensing>

Update licensee

Sets the provided properties to a licensee. Return an updated licensee.

HTTP Method / URL

POST /core/v2/rest/licensee/{licenseeNumber}

Security

Request Header

Accept: application/json | application/xml
Content-Type: application/x-www-form-urlencoded

Request Parameters

licenseeNumber (string) - Licensee number.

number (string) - Unique number (across all products of a vendor) that identifies the licensee. Vendor can assign this number when creating a licensee or let NetLicensing generate one. Read-only after creation of the first license for the licensee. Optional.

active (boolean) - If set to false, the licensee is disabled. Licensee can not obtain new licenses, and validation is disabled (tbd). Optional.

name (string) - Licensee name. Optional.

licenseeSecret (string) - Licensee Secret for licensee ((info) available in selected pricing plans). Optional. (warning) Deprecated, use Node-Locked Licensing Model instead.

markedForTransfer (boolean) - Mark licensee for transfer. Optional.

HTTP Status Code

200 - Successful request
400 - Malformed or illegal request
402 - Not allowed within your pricing plan
403 - Access is denied
404 - Resource not found
500 - Internal service error

See also JavaDoc: LicenseeService.update

Example

Request

POST https://go.netlicensing.io/core/v2/rest/licensee/IUI6MYNIC
number=IP53OX9PF&active=false&custLcseeProp2=custLcseePropVal2&custLcseeProp=custLcseePropValChanged
Accept: application/xml
Content-Type: application/x-www-form-urlencoded

Response

<netlicensing xmlns="http://netlicensing.labs64.com/schema/context">
    <items>
        <item type="Licensee">
            <property name="number">IP53OX9PF</property>
            <property name="active">false</property>
            <property name="productNumber">PJIF898SP</property>
            <property name="custLcseeProp">custLcseePropValChanged</property>
            <property name="custLcseeProp2">custLcseePropVal2</property>
        </item>
    </items>
</netlicensing>

Delete licensee

Delete a licensee by number.

HTTP Method / URL

DELETE /core/v2/rest/licensee/{licenseeNumber}?forceCascade

Security

Request Header

Accept: application/json | application/xml

Request Parameters

licenseeNumber (string) - Licensee number.

forceCascade (boolean) - Force object deletion and all descendants.

HTTP Status Code

204 - Successful request
400 - Malformed or illegal request
403 - Access is denied
404 - Resource not found
500 - Internal service error

See also JavaDoc: LicenseeService.delete

Example

Request

DELETE https://go.netlicensing.io/core/v2/rest/licensee/I001
Accept: application/xml

Response

HTTP/1.1 204 No Content

Validate licensee

Validates active licenses of the licensee.

HTTP Method / URL

POST /core/v2/rest/licensee/{licenseeNumber}/validate

Security
  • Basic Authentication
  • API Key Identification
    • ROLE_APIKEY_ADMIN
    • ROLE_APIKEY_MAINTENANCE
    • ROLE_APIKEY_OPERATION
    • ROLE_APIKEY_ANALYTICS
    • ROLE_APIKEY_LICENSEE

Request Header

Accept: application/json | application/xml

Content-Type: application/x-www-form-urlencoded

Request Parameters

licenseeNumber (string) - licensee number with a maximum length of 1000 characters
productNumber (string) (optional) - product number, must be provided when "licensee auto-create" is enabled (see also Product JavaDoc). Identifies the product to which new licensee should be added.
licenseeName (string) (optional) - human-readable name for the auto-created licensee (will be set as custom Licensee property)
licenseeSecret (string) (optional) - when provided and licensee secret enabled, will enable the licensee secret logic as described in Licensee Secret (deprecated)

Some product modules (depending on the licensing model) may require parameters passed on validate. Parameters to the product modules are passed using the following format:

productModuleNumber0 (string) - product module 0 number
<pmParam1>0
(any) - product module 0 parameter "<pmParam1>"
<pmParam2>0 (any)
- product module 0 parameter "<pmParam2>"
...
productModuleNumber1 (string)
- product module 1 number
<pmParam1>1 (any)
- product module 1 parameter "<pmParam1>"
...
productModuleNumber<N> (string)
- product module N number
<pmParam1><N> (any) - product module N parameter "<pmParam1>"
...

Notes:

  • <N> is 0-based decimal number incremented for every product module that receives parameters.
  • Order of product modules is not important.
  • For the <pmParamX> documentation refer to the corresponding licensing model.

HTTP Status Code

204 - Successful request
400 - Malformed or illegal request
403 - Access is denied
404 - Resource not found
500 - Internal service error

To use NetLicnesing effectively, validation must be up-to-date. On the other hand, performing validation requests too frequently will make response time of your service longer and create unnecessary load on the NetLicensing servers. Therefore it is recommended to keep last validation result on the client side and reuse it for a certain period for repeated validation requests. To determine the maximum validity duration of the validation response, NetLicensing returns an additional value with the validation response that is called „ttl“: it is the expiration timestamp of this validation response in ISO 8601 format.

See also JavaDoc: LicenseeService.validate

Example

Request

POST https://go.netlicensing.io/core/v2/rest/licensee/I011/validate
Accept: application/xml

Response

<netlicensing xmlns="http://netlicensing.labs64.com/schema/context" ttl="2015-11-03T15:02:36.137Z">
  <items>
    <item type="ProductModuleValidation">
      <property name="productModuleNumber">M011</property>
      <property name="productModuleName">Terminal Devices</property>
      <property name="licensingModel">Rental</property>
      <list name="L011">
        <property name="valid">false</property>
      </list>
      <list name="L012">
        <property name="valid">false</property>
      </list>
    </item>
  </items>
</netlicensing>

Try it now

$ curl --header "Accept: application/xml" --insecure --user demo:demo --request POST https://go.netlicensing.io/core/v2/rest/licensee/I011/validate

Icon

HTTP method GET is deprecated for licensee validate.

If you use RESTful API directly in your code, ensure to replace GET with POST for validate. GET method will be removed in one of the future releases, until then you’ll get the following warning if using GET:

Warning message

Response

<netlicensing xmlns="http://netlicensing.labs64.com/schema/context" ttl="2017-04-04T10:31:45.400Z">
  <ns2:infos>
        <ns2:info id="methodIsDeprecated" type="warning">'GET' method for licensee validate is deprecated, use 'POST' instead</ns2:info>
  </ns2:infos>
  <items>
    <item type="ProductModuleValidation">
      <property name="productModuleNumber">M011</property>
      <property name="productModuleName">Terminal Devices</property>
      <property name="licensingModel">Rental</property>
      <list name="L011">
        <property name="valid">false</property>
      </list>
      <list name="L012">
        <property name="valid">false</property>
      </list>
    </item>
  </items>
</netlicensing>

If using NetLicensing client library - update to the newest version.

Besides, new features associated with the validate method will not be available when called using GET.

 

Below specification for the GET method is only present here to help migrating from old code, please don’t use GET method for validate, use POST instead (see above)!

HTTP Method / URL

GET /core/v2/rest/licensee/{licenseeNumber}/validate[?productNumber={productNumber}&licenseeName={licenseeName}]

Security
  • Basic Authentication
  • API Key Identification
    • ROLE_APIKEY_ADMIN
    • ROLE_APIKEY_MAINTENANCE
    • ROLE_APIKEY_OPERATION
    • ROLE_APIKEY_ANALYTICS
    • ROLE_APIKEY_LICENSEE

Request Header

Accept: application/json | application/xml

Request Parameters

licenseeNumber (string) - licensee number with a maximum length of 1000 characters
productNumber (string) (optional) - product number, must be provided when "licensee auto-create" is enabled (see also Product JavaDoc). Identifies the product to which new licensee should be added.
licenseeName (string) (optional) - human-readable name for the auto-created licensee (will be set as custom Licensee property)
licenseeSecret (string) (optional) - when provided and licensee secret enabled, will enable the licensee secret logic as described in Licensee Secret (deprecated)

Some product modules (depending on the licensing model) may require parameters passed on validate. Parameters to the product modules are passed using the following format:

productModuleNumber0 (string) - product module 0 number
<pmParam1>0
(any) - product module 0 parameter "<pmParam1>"
<pmParam2>0 (any)
- product module 0 parameter "<pmParam2>"
...
productModuleNumber1 (string)
- product module 1 number
<pmParam1>1 (any)
- product module 1 parameter "<pmParam1>"
...
productModuleNumber<N> (string)
- product module N number
<pmParam1><N> (any) - product module N parameter "<pmParam1>"
...

Notes:

  • <N> is 0-based decimal number incremented for every product module that receives parameters.
  • Order of product modules is not important.
  • For the <pmParamX> documentation refer to the corresponding licensing model.

HTTP Status Code

204 - Successful request
400 - Malformed or illegal request
403 - Access is denied
404 - Resource not found
500 - Internal service error

Example

Request

GET https://go.netlicensing.io/core/v2/rest/licensee/I011/validate
Accept: application/xml

Response

<netlicensing xmlns="http://netlicensing.labs64.com/schema/context" ttl="2015-11-03T15:02:36.137Z">
  <items>
    <item type="ProductModuleValidation">
      <property name="productModuleNumber">M011</property>
      <property name="productModuleName">Terminal Devices</property>
      <property name="licensingModel">Rental</property>
      <list name="L011">
        <property name="valid">false</property>
      </list>
      <list name="L012">
        <property name="valid">false</property>
      </list>
    </item>
  </items>
</netlicensing>

Try it now

$ curl --header "Accept: application/xml" --insecure --user demo:demo --request GET https://go.netlicensing.io/core/v2/rest/licensee/I011/validate

 

Transfer licenses

Transfer licenses between licensees.

HTTP Method / URL

POST /core/v2/rest/licensee/{licenseeNumber}/transfer

Security
  • Basic Authentication
  • API Key Identification
    • ROLE_APIKEY_ADMIN
    • ROLE_APIKEY_MAINTENANCE
    • ROLE_APIKEY_OPERATION
    • ROLE_APIKEY_ANALYTICS
    • ROLE_APIKEY_LICENSEE

Request Header

Accept: application/json | application/xml

Request Parameters

licenseeNumber (string) - the number of licensee receiving licenses (max length: 1000 characters) - target

sourceLicenseeNumber (string) - the number of (temporary) licensee transferring its licenses (max length: 1000 characters) - source

HTTP Status Code

204 - Successful request
400 - Malformed or illegal request
403 - Access is denied
404 - Resource not found
500 - Internal service error

Icon

The following prerequisites must be fulfilled:

  • Licensees with sourceLicenseeNumber and licenseeNumber must be assigned to the same product
  • Source licensee must be marked for transfer (licensee custom property markedForTransfer must be set to ‘true’)


See also JavaDoc: LicenseeService.transfer

Example

Request

POST https://go.netlicensing.io/core/v2/rest/licensee/I011/transfer
sourceLicenseeNumber=ISourceLicensee
Accept: application/xml
Content-Type: application/x-www-form-urlencoded

Response

HTTP/1.1 204 No Content

Try it now

$ curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/xml' --header 'Authorization: Basic ZGVtbzpkZW1v' -d 'sourceLicenseeNumber=ISourceLicensee' 'https://go.netlicensing.io/core/v2/rest/licensee/I011/transfer'