Licensee Services

Licensees list
Get licensee
Create licensee
Update licensee
Delete licensee
Validate licensee
Transfer licenses

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

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

Create licensee

Creates a new licensee.

HTTP Method / URL	POST /core/v2/rest/licensee
Security	Basic Authentication API Key Identification ROLE_APIKEY_ADMIN ROLE_APIKEY_MAINTENANCE ROLE_APIKEY_OPERATION
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 ( available in selected pricing plans). Optional. 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	Basic Authentication API Key Identification ROLE_APIKEY_ADMIN ROLE_APIKEY_MAINTENANCE ROLE_APIKEY_OPERATION
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 ( available in selected pricing plans). Optional. 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	Basic Authentication API Key Identification ROLE_APIKEY_ADMIN ROLE_APIKEY_MAINTENANCE ROLE_APIKEY_OPERATION
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 or alias 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~~ (deprecated) (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

You can specify Licensee/Customer custom properties to be set in the validation request. These properties will be considered for all new customers upon initial validation.

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

Please Note: 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.

Please Note: 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

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'