The license object
Every field of a license as the server endpoints return it.
-
Every server endpoint that answers
{ license }returns it:GET /v1/licenses/:key, the license list, the checkout lookup, a test license, and the endpoints that change a key (extend, versions, devices, seat-release, user-lock and the meter routes). - Times are in Unix milliseconds.
{ "license": { "key": "MYPROD-9K4T-2M8P-XQ7V-H3DW", "product": "my-product", "model": "subscription", "modelId": "mod_5c1e0a7b9d2f4e8a6b3c1d0e9f8a7b6c", "modelName": "Annual", "status": "active", "kind": "active", "test": false, "email": "[email protected]", "expiresAt": 1822435200000, "term": null, "validUntil": 1823644800000, "deviceLimit": 3, "activeDevices": 1, "leaseDays": null, "graceDays": 14, "seatReleaseDays": 30, "userLock": "off", "seats": 1, "delivery": "key", "createdAt": 1790899200000, "revokedAt": null, "revokedReason": null, "versions": { "minMajor": 1, "maxMajor": null, "upgradeUntil": null }, "versionRule": null, "entitlements": { "edition": "pro" }, "meters": { "exports": { "uses": 1000, "extra": 500, "used": 950, "left": 550, "overage": 0, "offline": 150, "ownOffline": null, "resets": "never", "periodEnd": null } } }}Identity
The license key, as issued.
The API ID of its product.
Its type: perpetual, subscription, trial or timed.
The license model it was sold under and that model's current name, or null for a key sold under no model.
true for a test license.
The customer's email, or null.
When the key was issued.
The quantity bought in its Stripe or Paddle checkout, 1 otherwise. It is not the device limit.
- 1 on each key of a sale of several keys: the sale is what was bought.
Only on a key that is one of a sale of several keys: { id, index, size }, the sale's ID, this key's place in it (from 1) and how many keys it has. A key issued alone has no sale.
Status and term
active or revoked. A perpetual key past its expiry stays active; use kind to tell whether it still works.
- Up to a day after a subscription key's grace period ends or a trial key expires, KeyGrant revokes it.
The key's current state, the first that holds:
revokedif it is revoked.- Otherwise
expiredonce pastvalidUntil. - Otherwise
trialfor a trial key. - Otherwise
active. - A key inside its grace period is still
activeortrial.
When the key's term ends: a subscription's paid period, a trial's end, a timed key's term, or the expiry it was issued with.
nullfor a key with no expiry, and for a timed key still waiting for its first activation.
A timed key still waiting for its first activation: how long it runs once it starts, { months, days }, calendar months and days. null on every other key, a timed one that has started included (see Timed models).
When the key stops working: expiresAt plus its grace period, or null when it never stops.
- For a test license it is never
null: when the license has no expiry it is 30 days after creation, and it never includes grace.
The grace it runs on after its expiry, in days, copied from its license model when it was issued: 0 for none, and always 0 on a test license.
Its Offline days: how long each lease lives without a check-in, copied from its license model when it was issued (see Lease lifetime).
nullmeans its type's default: 30 days for a perpetual key, 7 for a subscription, trial or timed key.
When and why it was revoked: refund, chargeback, subscription_canceled or manual.
- A Stripe subscription that is canceled but still running to the end of its period also has them, with
subscription_canceled, whilestatusis stillactive. - A subscription key that ran out is revoked with
subscription_canceled, and a trial key that ran out withmanual.
Devices
How many devices may hold a seat: the license model's, unless the key has a limit of its own, from its issue, its import, its checkout's metadata or a later change. See Device limits and seats.
How many devices hold a seat now. It can be more than deviceLimit after the limit was lowered: lowering it releases no device.
How many days a device may go without checking in before its seat is freed, from its license model unless the key has its own; null when no seat is freed. See Free unused seats.
Who may activate a new device on the key: off, email or code, from its license model unless the key has its own. See Who can activate.
- A key with no
emailis asked of no one whatever this says. - Set with POST /v1/licenses/:key/user-lock.
Versions and entitlements
The majors it covers: minMajor to maxMajor (null means every later major too). While upgradeUntil is in the future, the key covers every major from minMajor up. See Licensing by version.
at_purchase or from_purchase when the key was sold without the version it needs: its first activation sets that version, and until then versions is provisional. null otherwise.
- A license file's key takes the product's current version when its file is made.
What it grants beyond the base product, the set its next lease will carry. {} for none.
Meters
What it counts, by meter code (see Metered uses); {} for none. Set with the meter routes.
Each meter has:
Its model's uses, or its own.
Uses added on top: top-ups, adds by hand, time bought again.
Spent this billing period, or for good.
The uses and the extra less what was used, never below 0.
What was used past both, which only a device back from offline can report.
The allowance a lease signs now.
The key's own allowance, null for the default.
never or period.
The end of the billing period a period meter is counting, when one is known.
Delivery
How the key was delivered, from its license model when it was issued: key (typed in by the customer), key_file (the same key in a signed file) or license_file (an offline file for good, perpetual only). A backend that sends its own mail fetches a file for a key_file or license_file key with POST /v1/licenses/:key/file.
What it does not include
The license object does not include the license's devices or their activation IDs (list them with GET /v1/licenses/:key/activations), its price, its last lease, or its Internal note.