How the system works

Three life cycles

Everything turns around three things: a license (the right to use, usually a key), a device (a machine holding a seat on a license) and a session (one run of your software that the server has confirmed).

License

• A new key is unused. Its duration, if it has one, starts at the first activation, not when it is made.
• Close to its end the license reads expiring, so the software can remind the user; past its end the plan's grace days apply (if set), then the software gets license_expired.
• Suspended can be lifted; revoked is final. Both take effect at the next call, and the software stops working offline when it hears either.
• TEST keys end 24 hours after they are made, with no grace. See Creating and managing licenses.

Device

• The fingerprint is built from hashed hardware identifiers (machine id, MAC, CPU); the raw values never leave the machine.
• Each install, the SDK makes a device key and keeps it on the machine. That key signs every request, so this machine's session is useless anywhere else.
• Each license has a device limit. A machine with a few parts changed is still the same machine when enough components match (3 by default).
• A machine silent longer than the plan allows (72 hours by default) gives its seat back; coming back with a seat free, it is the same machine again. Customers can move to another machine within the plan's limits. See Devices, HWID and transfers.

Session

• A session lives one hour without a heartbeat; the software sends one every few minutes while it runs.
• Sign-in and heartbeat answers say when to check in next, in a signed nextCheckSeconds (30 minutes by default). The SDK's nextCheckIn adds a spread of up to a fifth that stays the same for the machine, so thousands of copies do not call at once.
• On each activation and heartbeat, on every plan, the SDK receives a signed offline token, unless Online-Only Mode is on. Save it: without network, the SDK checks the token on the machine itself. It is valid only on that machine, until its own end (7 days by default, Premium chooses the length), and refused when the clock was turned back. A revoked license can keep working offline until then. See Offline licenses.

How your software talks to the server

Each scenario below has a sample project that runs in CI in every language; each app's Connect your software wizard downloads it with the settings filled in.

K1 · License key only

1. Software→ → Serverinit (version, fixes a wrong clock)
2. Software→ → Serveractivate(key, device)
3. Server→ → Softwaresession, license, entitlements, variables, offline token
4. The software saves the offline token to disk
5. Software→ → Serverheartbeat, every few minutes
6. Software→ → Serverlogout when it closes

No network on a later run: the SDK tries again, then reports network_error or timeout, the software checks the saved token and carries on while it is valid.

K2 · Accounts

1. Software→ → Serverregister(username, password), the first time
2. Server→ → Softwarean account on the free plan, and a session
3. Software→ → Serverlogin(username, password), the times after
4. Software→ → Serverredeem(key) when the customer buys
5. Server→ → Softwarethe upgraded account, new entitlements

A wrong password and an unknown account answer the same code (invalid_credentials), so nobody can probe for usernames.

K3 · Trial per machine

1. Software→ → Servertrial(device)
2. Server→ → Softwarea trial session and its end date
3. A machine that had its trial gets trial_used or trial_expired
4. Software→ → Serveractivate(key) when the customer enters one

Each machine gets one trial per app, reinstalls included.

K4 · End date and server variables

1. Software→ → Serveractivate(key)
2. Server→ → Softwarethe license with its end date and state
3. Software→ → Servervariables, with the session just opened
4. Server→ → Softwarethe app's, the license's and the user's variables

Variables are only readable with a valid session; a license's or user's own value overrides an app-wide one with the same name. See App variables.

K5 · Software updates

1. Software→ → Servercheck_updates(channel)
2. Server→ → Softwarethe new release's manifest, signed with the app key, valid for 10 minutes
3. The SDK trusts a manifest only when its signature, app and date are right
4. Software→ → Serverdownload through a link valid for 5 minutes
5. The SDK compares the file's SHA-256 with the manifest and refuses a mismatch

A build that is too old or blocked gets update_required or build_blocked right at init. See Signed releases and updates.

When something fails

Every failure is a code from one table shared by every SDK, the C library and the command line tool. The SDKs carry a sentence for the end user (in English and Vietnamese) and know which codes are worth retrying later. See Error codes.

The SDKs also try again by themselves, with a growing random wait, two more times by default:

• No answer, or an unsigned 5xx page. Only calls that are safe to repeat: init, activate, login, heartbeat, variables, updates, logout and report. trial, register, redeem and transfer are never repeated after a lost answer, because they may already have happened.
• The server asks to wait. A signed rate_limited, or an unsigned 429 or 503, is retried on any call, obeying Retry-After up to 30 seconds.

Only a verified signature changes license state: an unsigned page from something in between is just a failed try. The retry count and spare addresses are SDK options (maxRetries and fallbackUrls in JavaScript), and 0 retries turns this off.

The deeper layer: why it cannot be faked

• Signatures both ways. Every request is signed by the device key (Ed25519) over its whole content, its time and a one-time number. Every answer, errors included, is signed by the app key and bound to that request, its path and its status. The SDK needs only the app's public key to check, so shipping it is safe.
• No replays. The server remembers one-time numbers for a few minutes and accepts requests at most 60 seconds off; with a wrong clock the SDK corrects itself from a signed answer and sends again.
• A fake server gets nowhere. An unsigned answer, one signed with another key, altered or too old, is refused by the SDK like no answer at all, and reported to Protect at the next good call.

The full specification and the test vectors, for those writing their own client: CLV1 protocol specification.