How license keys work
How software license keys are generated and validated, per-product key prefixes, member license keys for teams, reissuing a leaked key, and offline tokens.
A license key looks like a random string, but how it is made decides almost everything else: whether it can be cracked, whether you can revoke it, and whether your app works without a network connection. This page walks through the usual approaches and why Keygate uses the one it does.
Three ways to make a key
Algorithmic keys
The oldest approach: the key is built by a formula, for example a few characters plus a checksum, and the app checks it by running the same formula. No server is needed. The problem is that the formula ships inside every copy of the app. Once someone extracts it, they can write a key generator, and every key it produces is as valid as one you sold. There is also no way to take a key back.
Signed keys
The key is a small piece of data, such as the customer and an end date, signed with a private key. The app holds only the public key, so it can check the signature but cannot create new keys. That fixes key generators. It still leaves keys that cannot be revoked, and the keys get long, because a signature alone is 64 bytes or more.
Random keys checked by a server
The key is just a random identifier, and a server knows what it belongs to. The app asks the server whether the key is valid. Keys stay short, can be revoked or refunded at any time, and the server can limit how many devices use each one. The cost is that the app needs the server at least once.
Keygate combines the last two: keys are random and checked by your server, and every answer from the server comes with a signed token the app can check offline afterwards.
| Approach | Can be cracked by a key generator | Can be revoked | Works offline |
|---|---|---|---|
| Algorithmic | Yes | No | Yes |
| Signed | No | No | Yes |
| Random, checked by a server | No | Yes | No |
| Random plus signed tokens (Keygate) | No | Yes | Yes, after activation |
Generating a random key
A random key needs two things: enough randomness that nobody can guess one, and a format people can type. Keygate keys look like KG-4F2TLTRG-RWFPA6X4-WHZU639Y-2ADL6KY2: 32 characters from an alphabet without look alike characters such as I, O, 0 and 1. That is about 160 bits of randomness, far beyond what anyone can guess. In Python the same idea takes a few lines:
import secrets
ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" # no I, O, 0 or 1
def new_key(prefix: str = "KG") -> str:
groups = ["".join(secrets.choice(ALPHABET) for _ in range(8)) for _ in range(4)]
return "-".join([prefix, *groups])Use a cryptographic random source, secrets in Python or crypto/rand in Go, never the ordinary random module, whose output can be predicted.
License key prefix
The first segment of a Keygate key is a prefix chosen per product, so a customer, or your support team, can tell from the key which product it belongs to. It is KG unless you change it. Set it under License key prefix when you create or edit a product in the dashboard, or send license_prefix to POST /admin/products or PUT /admin/products/:id.
- It is 2 to 8 characters, letters A to Z and digits only. Lowercase letters are turned into capitals. Any other character, or a length outside 2 to 8, answers
400 BAD_REQUEST. - A change applies to keys issued from then on: new licenses, members' own keys and reissued keys. Keys already issued keep the prefix they were made with and keep working, because Keygate looks a key up by a hash of the whole key.
- The prefix is a label, not a secret, and it adds no security. The 32 random characters after it are what keep a key from being guessed.
If your app checks the format of a key before sending it, for example to tell a Keygate key from one of an older system, accept any prefix of 2 to 8 capitals and digits rather than only KG.
Validating a key
Checking a random key happens in two steps:
- Activation, once: the app sends the key and an identifier for the device. The server checks that the license is active and that a device slot is free, then records the device.
- Verification, from then on: the app sends the same pair, and the server answers whether this device may still use the license.
Verification should look the same for every kind of failure. If a made up key answers differently from a revoked one, anyone can use the difference to find real keys. Keygate answers verify with 404 LICENSE_NOT_FOUND in every case, and locks out an address after repeated failed calls. Activating licenses in your app shows the calls in full.
Working offline
Asking the server on every start would lock customers out on a plane or behind a firewall. So after each successful check, Keygate returns a token signed with Ed25519. It names the license, the device and the time the app should check in again. The app stores it and verifies the signature with a public key on later starts, without any network call. When the token is due, the app asks the server again and gets a fresh one.
How long a token lasts is a trade off you choose per plan: a week is a common default. Shorter means a canceled license stops working sooner; longer suits customers who are often offline.
Member license keys
On a license shared by a team, every member has a license key of their own, so nobody has to pass the owner's key around. This applies to SaaS and hybrid products, the types that have team seats. The owner invites people from the customer portal; once a member accepts, their key is shown to them in the portal. It starts with the product's prefix, like any other key.
A member's key works wherever the license key does: activate, verify, deactivate, floating checkout, entitlements and usage. It opens the same license, with the same plan, features and device limit. What differs is whose devices it manages:
- Every device and floating session records the key that activated it. A member's key verifies, deactivates and renews only its own devices and sessions. Asked about anyone else's device, it answers like an unknown key.
- A device stays with the key that activated it. A member's key on a device that another key on the license has activated is refused with
409 DEVICE_HELD. The owner can remove that device in the portal, and the member then activates it as their own. - The license key, which the owner keeps, manages every device and session on the license, members' included.
- Devices activated with the license key before member keys existed (before Keygate v0.1.17), when members used the shared key, are the exception: such a device moves, once, to the first member who activates it with their own key. The app gets
already_activatedand no slot is used. - All devices count toward the one device limit of the license, whichever key activated them.
Removing a member revokes their key at once and removes the devices and floating sessions it activated, which frees their slots. The owner's key does not change when members come and go.
Keys of paused members
A license can end up holding more people than its seat limit, for example when an admin lowers the plan's max seats or the seats bought go down. The owner always counts as one of the seats and is never paused. Of the members, those who joined last are paused until a seat is free. A paused member's key is refused:
- Activate answers
403 SEAT_PAUSED, so the app can say why. - Verify, floating checkout, entitlements and usage answer
404 LICENSE_NOT_FOUND, the same as any key that cannot be used. Deactivate still works, so the member can free their own devices. - A token issued before the pause keeps working offline until it is due, then the next verify fails.
As soon as a seat is free, because the owner removed a member, bought more seats or moved to a plan with more, or because you raised the plan's max seats, the next member in line can use their key again. Nothing is stored about the pause, so there is nothing to undo.
Reissuing a license key
Once issued, a license key does not change for the customer: there is no button in the portal that replaces it. If a key leaks, you reissue it from the dashboard with Reissue key on the license, or with POST /admin/licenses/:id/rotate-key.
- The old key stops working at once. The devices and floating sessions activated with it are removed, and a
license.deactivatedwebhook is sent for each device. That includes devices from before member keys that no member has moved to their own key yet. - Members' own keys, devices and sessions are not affected.
- The new key uses the product's current prefix. The owner is not told: send it to them, for example with Resend email, which mails the key while the license is usable.
A single member's key is reissued the same way from the license's member list, or with POST /admin/licenses/:id/seats/:seat_id/rotate-key. Their old key and its devices go; the new key is shown in the dashboard and in the member's portal.
Common mistakes
- Putting a secret in the app. An API key or private key inside a shipped app can be extracted. The license key itself should be the only credential the app sends.
- An identifier that changes. If the device identifier changes between runs, every start looks like a new device and uses up a slot. Use the operating system's machine ID.
- Locking people out when the network fails. Flaky connections are far more common than pirates. Give a few days of grace before turning features off.
- Forgetting refunds. A key should stop working when its payment is refunded or disputed, which means your payment provider has to reach your license system.
Frequently asked questions
Can I change the license key prefix after keys are issued?
Yes. The new prefix applies to license keys and member keys issued from then on. Keys already issued keep their old prefix and keep working, because Keygate finds a key by a hash of the whole key, not by its prefix.
Do team members share the owner's license key?
No. Each member who accepts an invitation gets a license key of their own, shown to them in the customer portal. It opens the same license, but only manages the devices that member activated. The owner keeps the license key.
What happens to a member's key when they are removed?
It stops working at once. The devices and floating sessions activated with it are removed, so their slots are free again. If the member is invited back later, they get a new key.
How do I replace a license key that leaked?
Open the license in the dashboard and use Reissue key, or call POST /api/v1/admin/licenses/:id/rotate-key. The old key stops working and the devices activated with it are removed. The customer is not told, so send them the new key, for example with Resend email. A member's key is reissued the same way from the member list.
Last updated October 26, 2026