Get Key - Devolens (formerly Cryptolens) Documentation

Assumed ModelVersion: 3 (highest documented version at generation time) This method will return information about a license key, similar to Validate [Web API 2]. In contrast to activation, this method (aka Key Validation) will be in read only mode. That is, it will not add a device to the license nor use trial activation. More about this in Remarks. This method is accessed by https://api.cryptolens.io/api/key/GetKey

Parameters

Parameter	Description	Remarks
ProductId	the product id (=[ProductId] )	required
Key	the serial key string	required
Sign	If true, the information inside the LiceseKey object will be signed.	optional. false by default.
FieldsToReturn	An integer that allows you to restrict the information returned in the license key data object.	optional. 0 by default = all fields returned.
SignMethod	Specifies the format of the result and the way it should be signed.	optional. 0 by default.
Metadata	Includes additional information about the license key, such as number of activated devices, etc.	optional. false by default.
FloatingTimeInterval	If Metadata is set to true, setting this to something greater than 0 will return the number of active floating licenses. You can read more about the way it works on this page.	optional. 0 by default.
ModelVersion	The model that will be returned. In comparison to method version, this only affects what fields and information will be returned and does not impact the way the method works. A changelog can be found in the end of this page.	optional. by default, it’s 1.
v	Method version.	optional. by default, it’s 1.

Results

Parameter	Description	Remarks
LicenseKey	A LicenseKey object. The structure is described in License Key section. If SignMethod is set to 1, the License Key will be a string representation of the object converted into base64 (all DateTime fields are expressed as 64 bit integers in Unix time).	always returned
Signature	The signature of the base64 representation of the LicenseKey field (above).	returned if SignMethod=1
Metadata	Includes additional information about the license key, such as number of activated devices, etc.	returned if Metadata=True
Result	This is either 0(=success) or 1(=error).	always returned
Message	The message that provides additional information about the result. If it’s a successful result, either null or the new key (if using SKGL) will be returned. Otherwise, in case of an error, a short message will be returned describing the error.	always returned.

License Key (FieldsToReturn=0)

Parameter	Description	Remarks
ProductId	The ID of the product that this key belongs to.	always returned
ID	The ID (within the product) of the license key.	depends on configuration
Key	The license key string, eg. ABCDE-EFGHI-JKLMO-PQRST.	depends on configuration
Created	The creation date of the license key.	always returned
Expires	The expiration date of the license key. Note, it’s optional and it’s up to your program to interpret this. Please see Key’s that don’t expire.	always returned
Period	The duration of current license cycle eg. 30 days. Note, this is a static number and does not change automatically.	always returned
F1	The feature 1 of the license key.	always returned
F2	The feature 2 of the license key.	always returned
F3	The feature 3 of the license key.	always returned
F4	The feature 4 of the license key.	always returned
F5	The feature 5 of the license key.	always returned
F6	The feature 6 of the license key.	always returned
F7	The feature 7 of the license key.	always returned
F8	The feature 8 of the license key.	always returned
Notes	The notes field of the license key.	depends on configuration
Block	This will always be false.	always returned
GlobalId	A unique identifier of the license key. It can, for instance, be used as a “ReferencerId” when creating a data object(aka additional variables).	depends on configuration
Customer	The entire customer object assigned to this license key.	depends on configuration
ActivatedMachines	A list of Activation data. It will include both node-locked and floating licenses. In the case of floating licenses, it will list all of the floating machines that have not expired, even if the FloatingTimeInterval is smaller. If you only want to see floating devices that would be permitted within a certain FloatingTimeInterval, then you can filter them as follows: FloatingExpires ≤ UTCNow.AddSeconds(FloatingTimeInterval). For more information on the difference between floating and node-locked licenses, please see this article.	depends on configuration
TrialActivation	Tells if trial activation is enabled.	always returned
MaxNoOfMachines	The maximum number of machines/devices that may activate this license. By setting this to 0, machine locking will be disabled and an unlimited number of devices will be able to activate the license.	depends on configuration
AllowedMachines	Machine codes of those devices that will be prioritized during activation. Even if the limit is achieved, these will still be activated.	depends on configuration
DataObjects	A list of Data objects, additional variables associated with the license key.	depends on configuration
Reseller	The entire reseller object assigned to this license key.	depends on configuration
SignDate	The DateTime when this activation file was signed.	always returned
Signature	The signature of the all the fields above	Returned if Sign=true.

Metadata (FieldsToReturn=0)

You can hide metadata by checking.

Parameter	Description	Remarks
ActivatedMachines	The number of activated machines for this license key.	depends on configuration
LicenseStatus	Additional information about the license key. It contains the following: IsValid - Either true or false, depending on if the license satisfies all conditions for being valid. ReasonForInvalidity - if a license is invalid, this will contain the reason (an integer). This can be decoded as follows: None = 0 Expired = 1 Blocked = 2 Trial - tells if the license is a trial, based on the feature definitions for the product TimeLimited - tells if the license is a time-limited / subscription, based on the feature definitions for the product TimeLeft - if the license key is time-limited, this field will contain the remaining number of days until it expires	depends on configuration
ActivatedMachines	The signature of the metadata object.	Returned if sign=true.
UsedFloatingMachines	The number of active floating machine codes for a specific FloatingTimeInterval. Tip: If you want to find the number of unused machines, subtract this value from maxNumberOfMachines. If overdraft is used, you need to add the maxOverdraft value to maxNumberOfMachines.	depends on configuration

Example results

If SignMethod=0

{"productId":1234,"licenseKey":{"id":1,"key":"AAAAA-AAAAA-AAAAA-AAAAA","created":"2015-08-27T00:00:00","expires":"2018-11-03T00:00:00","period":1023,"f1":true,"f2":false,"f3":false,"f4":false,"f5":false,"f6":false,"f7":false,"f8":false,"notes":"this key is used as an example in one of the test cases.","block":false,"globalId":24963,"customer":{"id":3,"name":"Bob","email":"[email protected]","companyName":"SKM","created":"2015-09-04T16:11:14.453"},"activatedMachines":[{"mid":"5632812","ip":"10.1.1.1","time":"2016-03-25T18:56:34.647"},{"mid":"7632812","ip":"10.1.1.2","time":"2016-04-06T15:05:35.733"},{"mid":"85256631","ip":"10.1.1.5","time":"2016-04-07T22:18:26.673"}],"trialActivation":false,"maxNoOfMachines":10,"allowedMachines":"","dataObjects":[],"signDate":"2016-04-11T09:45:06","signature":null},"result":0,"message":""}

If SignMethod=1

{"licenseKey":"eyJQcm9kdWN0SWQiOjMsIklEIjo2LCJLZXkiOiJHT1hHWi1WQUNLRS1TUUJZRS1CUlhVUCIsIkNyZWF0ZWQiOiIyMDE0LTAxLTAyVDAwOjAwOjAwIiwiRXhwaXJlcyI6IjIwMTQtMDItMTZUMDA6MDA6MDAiLCJQZXJpb2QiOjQ1LCJGMSI6dHJ1ZSwiRjIiOnRydWUsIkYzIjpmYWxzZSwiRjQiOmZhbHNlLCJGNSI6ZmFsc2UsIkY2IjpmYWxzZSwiRjciOmZhbHNlLCJGOCI6ZmFsc2UsIk5vdGVzIjoidG8gU2NvdCIsIkJsb2NrIjpmYWxzZSwiR2xvYmFsSWQiOjEwMDksIkN1c3RvbWVyIjp7IklkIjoyNywiTmFtZSI6ImN1c3RvbWVyIiwiRW1haWwiOiJhcnRlbUBhcnRlbWxvcy5uZXQiLCJDb21wYW55TmFtZSI6InRlc3QiLCJDcmVhdGVkIjoiMjAxNi0wMS0wNFQxOTo0OTowOS4zMDcifSwiQWN0aXZhdGVkTWFjaGluZXMiOltdLCJUcmlhbEFjdGl2YXRpb24iOmZhbHNlLCJNYXhOb09mTWFjaGluZXMiOi0xLCJBbGxvd2VkTWFjaGluZXMiOm51bGwsIkRhdGFPYmplY3RzIjpbXSwiU2lnbkRhdGUiOiIyMDE3LTA0LTE0VDE0OjE1OjM4IiwiU2lnbmF0dXJlIjpudWxsfQ==","signature":"fVhV2revZTug1HtYcLkSEEMCPk0AkaBWBl4cRYOXlOpHR5S7xNtcY9o+wXRuauNXzGXh5LQcT8Ybo1HJ1LFp3z7sEfoDZZHfckbKbeSOTi+ercuqH26nWdvD2wgKsJsU0Rx6iClyKezNS36azriubdxcVabClFawn65GHexw14AeQlGU1jreAs0N57Dw/jwuBPXGfId64V8daOozVJQFhJVA6B1ZSu01FfxuBQxn2kj+UhjRGMp79JasCu2h1V5End66IHf0jlbgfsRDlWGfik1oK1LhFfkVV9rURSWiINhh1rZn1NM4ELHr/ASXUj1P1PdrtPadobDO+eXDUZhBHQ==","result":0,"message":""}

Remarks

The feature lock value is used to store the filedsToReturn value. If you set a certain value in the feature lock, it will be prioritized higher than the fieldsToReturn parameter.
To compute the value of the feature lock, please use the Hide column, for those fields that you want to omit in the result above.
Hiding a column using the filedsToReturn does not remove the field from the result. It only removes the value of the field, for example by setting it to null.
(For first time use) Before you proceed with signing, please visit this page to generate your public/private key pair.
The SignMethod currently supports two ways of returning the license key information and signing the content. Linq Sign (0) - The default option supported in the SKM Client API for.NET. Everything is returned as a JSON dictionary with a signature attached to the license key object.
String Sign (1) - This option is tailored for cross platform applications and is the preferred way retrieving signed versions of the license key object. The license key is converted into a json string which is later stored in base64. This is then signed using RSA 2048 with SHA256.

Please note that in both cases, Sign has to be set to true if you want the license key to be signed.

Errors

Error
Access denied.
The input parameters were incorrect.
Could not find the product.
Could not find the key.

Model Versions

This changelog list changes of the returned fields given the model version.

This model has a few changes. First, we have added a Reseller object to the LicenseKey. Secondly, we have made sure that all node-locked and floating licenses are returned (unless field masking is used). We added FloatingExpires to ActivatedMachines so that you can check when the activatin was set to expire (note, this value can be overrriden when calling this method with a different FloatingTimeInterval).
Add FriendlyName to ActivatedMachines in the license key.
The original model.

FAQ

Can GetKey replace activation or a floating heartbeat?

GetKey requires the GetKey token permission and only retrieves information. It does not register a device, start trial activation, or acquire or renew a floating seat, even when floating usage metadata is requested. Use Activate for acquisition and renewal. A daily GetKey refresh and usage-counter updates do not extend a floating process’s last confirmed validity window.

Can GetKey return a blocked or expired license?

Yes. Successful retrieval is not permission to use the license. GetKey can return a license with Block=true, which your application must reject. Check Expires according to your licensing policy; retrieving the license does not enforce that policy for you. Request a signed response with Sign=true, verify its signature and expected product and license identity, and check required features and machine binding where configured. Cached and manually delivered files also require a signed-age check. An explicit API rejection, invalid signature, or failed license check must not be overridden with an older file. See the validation checklist and offline verification flow.

​Parameters

​Results

​License Key (FieldsToReturn=0)

​Metadata (FieldsToReturn=0)

​Example results

​Remarks

​Errors

​Model Versions

​FAQ

​Can GetKey replace activation or a floating heartbeat?

​Can GetKey return a blocked or expired license?