Documentation menu▾

Activating licenses in your app

Activate a license key from your app, verify it on startup, keep working offline with a signed Ed25519 token, handle team member keys and free a device.

Your app needs three calls to the license API: activate once when the user enters a key, verify when the app starts, and deactivate when the user moves to another computer. None of them needs an API key. The license key is the credential, so there is no secret to hide inside your app.

All three take JSON and are served under /api/v1/license on your Keygate address. For complete code in a specific framework, see the guides for Electron, Tauri, .NET, Python and Swift.

How it works

For why Keygate uses random keys plus signed tokens instead of keys your app checks by itself, see How license keys work.

  1. The user types their license key. Your app calls activate with the key and an identifier for the device. Keygate records the activation and returns a signed token.
  2. Your app saves the key and the token. On every start it checks the token locally. If the token is still within its check in interval, the app runs without touching the network.
  3. When the token is due, the app calls verify and gets a fresh token, along with the current plan and features. If the license was canceled or revoked in the meantime, the answer says so.
  4. When the user switches computers, the app calls deactivate and the slot is free for the new machine.

Choosing an identifier

The identifier tells Keygate which device an activation belongs to. It must stay the same for the same machine, or every restart would look like a new device and use up a slot. Good sources are the operating system's machine ID: IOPlatformUUID on macOS, the MachineGuid registry value on Windows, /etc/machine-id on Linux. Hashing the value before you send it is a good habit, since you only need it to be stable, not readable.

If you license by person instead of by machine, send the user's email as the identifier. Activation works on desktop and hybrid products; a SaaS product counts people as seats instead.

Activating

bash
curl -X POST https://licenses.example.com/api/v1/license/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789",
    "identifier": "9f2c41e07b6a",
    "label": "Office iMac"
  }'
FieldRequiredNotes
license_keyYesThe key the customer entered.
identifierYesStable ID of the device, or the user's email. Trimmed, and at most 256 bytes.
identifier_typeNodevice (the default) or user, stored with the activation as a label. Anything else answers 400.
labelNoA name the customer will recognize in the portal, such as the computer's name. At most 256 characters.

A successful answer:

json
{
  "success": true,
  "data": {
    "status": "activated",
    "license_id": "4f0c6c1e-2a7b-4d4e-9a55-0d3b7e1f2c11",
    "token": "eyJsaWQiOiI0ZjBj...In0.Xk3m9QJ..."
  }
}

Calling activate again from a device that is already active returns already_activated and does not use another slot, so it is safe to call whenever you are unsure.

The device limit is the plan's max activations. On a plan sold per seat it is max activations for each seat the customer pays for, so a five seat license with 2 devices per seat holds 10 devices.

Verifying on startup

bash
curl -X POST https://licenses.example.com/api/v1/license/verify \
  -H "Content-Type: application/json" \
  -d '{"license_key":"KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789","identifier":"9f2c41e07b6a"}'
json
{
  "success": true,
  "data": {
    "status": "active",
    "plan_id": "c2b7...",
    "plan_name": "Pro",
    "valid_until": "2027-10-04T00:00:00Z",
    "features": { "export_pdf": true, "projects": "50" },
    "grace_days": 7,
    "token": "eyJsaWQiOiI0ZjBj...In0.Q8vR2..."
  }
}

valid_until is missing for licenses that never expire. A perpetual license with an update period also returns updates_until, the last date whose releases it may install.

Working offline

Every activate and verify answer contains a token signed with Ed25519. Your app can check it without a network connection, which is what lets it start on a plane or behind a firewall.

Get the public key

Fetch the verification key once and ship it inside your app. It only changes if you change LICENSE_SIGNING_KEY on the server.

bash
curl https://licenses.example.com/api/v1/license/pubkey
{"success":true,"data":{"algorithm":"ed25519","format":"hex","public_key":"3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29"}}

Check the token

A token is two base64url strings joined by a dot: the payload and its signature. The signature covers the payload exactly as it appears in the token, before decoding. In Node.js:

javascript
import { createPublicKey, verify } from "node:crypto";

const PUBLIC_KEY_HEX = "3b6a27bc..."; // from /api/v1/license/pubkey

// Wrap the raw 32 byte key in the DER header Node expects for Ed25519.
const publicKey = createPublicKey({
  key: Buffer.concat([
    Buffer.from("302a300506032b6570032100", "hex"),
    Buffer.from(PUBLIC_KEY_HEX, "hex"),
  ]),
  format: "der",
  type: "spki",
});

export function readToken(token, identifier) {
  const [payload, signature] = token.split(".");
  const valid = verify(null, Buffer.from(payload), publicKey, Buffer.from(signature, "base64url"));
  if (!valid) return null;

  const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
  if (claims.did !== identifier) return null; // issued to another device
  return claims;
}

The same in Go:

go
func readToken(token, identifier string, publicKey ed25519.PublicKey) (map[string]any, bool) {
	payload, signature, ok := strings.Cut(token, ".")
	if !ok {
		return nil, false
	}
	sig, err := base64.RawURLEncoding.DecodeString(signature)
	if err != nil || !ed25519.Verify(publicKey, []byte(payload), sig) {
		return nil, false
	}
	raw, err := base64.RawURLEncoding.DecodeString(payload)
	if err != nil {
		return nil, false
	}
	var claims map[string]any
	if json.Unmarshal(raw, &claims) != nil || claims["did"] != identifier {
		return nil, false
	}
	return claims, true
}

What the token contains

All times are Unix seconds.

FieldMeaning
lidLicense ID. pid and pln are the product and plan IDs.
stsLicense status when the token was issued.
didThe identifier the token was issued to.
ftrThe plan's features, the same as in the verify answer.
iatWhen the token was issued. exp is when the app should check in again: the check in interval from now, or the end of the license plus its grace days if that comes sooner.
vunWhen the license itself ends. Missing means it never does.
grcGrace days after vun, the same as grace_days in the verify answer. At least 1 for a trial that moves to a free plan when it ends, see below.
updEnd of the update period, for perpetual licenses that have one. Install only releases published before it.

Trials that move to a free plan

A trial plan can name a free plan that its licenses move to when the trial ends, instead of expiring. Moving a trial to a free plan explains how to set it up. For your app it changes two things.

  • The server makes the move in a check that runs every hour, so it can come up to an hour after valid_until. To keep the license working in between, grace_days and the token's grc are at least 1 for such a trial, even when the plan has no grace days. A trial that Stripe bills is left to Stripe and keeps the plan's own grace days.
  • After the move, verify answers active with the free plan's plan_id, plan_name and features, and no valid_until. The key and the activation stay, so the app does not activate again. Save the new token and apply the features it lists.

Putting it together

  • If the token is valid and exp is in the future, run normally.
  • If exp has passed, call verify. On success, save the new token and run.
  • If verify cannot reach the server, decide how strict to be. Most apps give a few days of warning before locking features, because flaky networks are far more common than pirates.
  • If verify answers 404, the license no longer works on this device.

How long the token lasts is the check in interval on the plan. A week is a reasonable default; shorter intervals make cancellations take effect sooner, longer ones suit apps that are often offline.

Deactivating

bash
curl -X POST https://licenses.example.com/api/v1/license/deactivate \
  -H "Content-Type: application/json" \
  -d '{"license_key":"KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789","identifier":"9f2c41e07b6a"}'

Offer this in your app's settings, for example as a Deactivate this computer button, and delete the stored key and token afterwards. Customers who no longer have the old machine can free the slot themselves in the customer portal, so a lost laptop does not turn into a support ticket.

Member license keys

When a license of a hybrid product is shared by a team, each member has a license key of their own and enters it in your app instead of the owner's key. Member license keys explains where members find it. Your app makes the same three calls with it and needs no changes, but the answers depend on whose device it is:

  • Activate with a member's key takes a slot from the license's one device limit. On a device that another key on the license already activated, it answers 409 DEVICE_HELD. A device activated with the owner's key before member keys existed is the exception: it moves to the member and the answer is already_activated.
  • Verify and deactivate with a member's key work only on devices that key activated. Any other device answers 404 LICENSE_NOT_FOUND.
  • The owner's license key verifies and deactivates every device on the license, members' included, and activate with it on a member's device answers already_activated.
  • A paused member, one beyond the license's seat limit, gets 403 SEAT_PAUSED from activate and 404 LICENSE_NOT_FOUND from verify until a seat is free. Deactivate still works.
  • When the owner removes a member, the member's key stops working and their devices are removed: verify answers 404 LICENSE_NOT_FOUND.

Floating checkout follows the same rule: a member's key renews and checks in only its own sessions, and a running session taken with another key answers 409 SESSION_HELD. See Floating licenses.

Handling errors

Errors come back in the same envelope with a code you can branch on. These are the ones an app usually needs to handle:

StatusCodeWhat to tell the user
404LICENSE_NOT_FOUNDThe key is wrong, or the license no longer works here. Ask for a key again.
409ACTIVATION_LIMITAll devices are in use. The answer includes details.current and details.max. Point the user to the customer portal to free one.
409DEVICE_HELDA member's key was used on a device that another key on the license activated. The license owner can remove that device in the customer portal; then activate again.
403SEAT_PAUSEDThe key belongs to a team member who is paused because the license has more people than seats. Ask the license owner to remove a member or get more seats.
409FLOATING_LICENSEThe license is on a floating plan, which takes seats through floating checkout instead of activation.
403LICENSE_EXPIRED, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_CANCELEDReturned by activate when the license exists but cannot be used. Show the reason.
404FEATURE_NOT_AVAILABLEThe product is a SaaS product, which has no device activations. Use a desktop or hybrid product.
429LOCKED_OUTToo many failed attempts from this network. Wait a little and try again.

The API reference has the full rules for errors and retries, and Troubleshooting explains the usual causes of each code.

Retries

Activation is safe to repeat, but if your app retries after a timeout, send an Idempotency-Key header. Generate one random value when the user starts the activation and send the same value with every retry of it. A retry with the same key gets the first answer back instead of being processed twice. Keys are remembered for 24 hours.

bash
curl -X POST https://licenses.example.com/api/v1/license/activate \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d8a52-3c0e-4b7a-9f2e-1a4c7d9e0b35" \
  -d '{"license_key":"KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789","identifier":"9f2c41e07b6a"}'

Frequently asked questions

Does my app need an API key to activate a license?

No. Activate, verify and deactivate take no API key. The license key the customer enters is the credential, so there is no secret to hide in your app. Never ship an admin API key inside an app.

What happens if my app calls activate twice on the same device?

The second call answers already_activated with a fresh token and does not use another device slot. It is safe to call activate whenever the app is unsure whether the device is active.

How long can my app run without a network connection?

Until the token's exp, which is the plan's check in interval after the last successful activate or verify, seven days by default, and never later than the end of the license plus its grace days. After that the app has to reach the server again.

Do team members enter the owner's license key in the app?

No. Each member has their own license key, shown in the customer portal, and enters that one. It works with the same calls. A member's key only verifies and deactivates the devices it activated.

Last updated October 26, 2026