> ## Documentation Index
> Fetch the complete documentation index at: https://help.cryptolens.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Key

> 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...

Assumed ModelVersion: 3 (highest documented version at generation time)

This method will return information about a license key, similar to [Validate \[Web API 2\]](https://app.cryptolens.io/docs/api/v2/Validate).
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](https://help.cryptolens.io/web-interface/trial-activation).
More about this in [Remarks](/api-reference/generated/GetKey#remarks).

This method is accessed by [https://api.cryptolens.io/api/key/GetKey](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](/api-reference/generated/GetKey#metadata-fieldstoreturn=0) 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](/api-reference/generated/Activate). | 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](/api-reference/generated/GetKey#model-versions). | 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](/api-reference/generated/GetKey#license-key-fieldstoreturn=0) section. If **SignMethod** is set to 1, the [License Key](/api-reference/generated/GetKey#license-key-fieldstoreturn=0) 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](/api-reference/generated/GetKey#metadata-fieldstoreturn=0) 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** | **Hide?** |
| - | - | - | - |
| 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](https://help.cryptolens.io/web-interface/keys-that-dont-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)](/api-reference/generated/DataObjectsIntro). | depends on configuration | |
| Customer | The entire [customer](/api-reference/generated/model/Customer) object assigned to this license key. | depends on configuration | |
| ActivatedMachines | A list of [Activation data](/api-reference/generated/model/ActivationData). 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](https://help.cryptolens.io/faq#whats-the-difference-between-node-locked-vs-floating-licenses). | depends on configuration | |
| TrialActivation | Tells if [trial activation](https://help.cryptolens.io/web-interface/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](/api-reference/generated/model/DataObject), additional variables associated with the license key. | depends on configuration | |
| Reseller | The entire [reseller](/api-reference/generated/model/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** | **Hide?** |
| - | - | - | - |
| 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**

```text theme={null}
{"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":"bob@example.com","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**

```text theme={null}
{"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](/api-reference/generated/GetKey#license-key-fieldstoreturn=0).
* 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](https://app.cryptolens.io/User/Security) 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.

3. 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*).
4. Add **FriendlyName** to **ActivatedMachines** in the license key.
5. 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](/api-reference/generated/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](https://help.cryptolens.io/examples/key-verification#does-a-successful-api-response-mean-the-license-is-valid)
and [offline verification flow](https://help.cryptolens.io/examples/offline-verification).