The idea in one paragraph
A license check normally asks a server “is this key valid?” and reads the answer. That fails when the network is down, and it trusts whatever answers. An offline check changes the shape. The server answers once, signs the answer with a private key and hands the signed answer to the app. Later, the app verifies the signature with the matching public key, which ships inside the app. If the signature is good and the answer is recent enough, the app runs. The network is not involved.
The cost is that the answer can go out of date. A token says what the license looked like when it was signed. That is why every token has a deadline.
What a real token looks like
This is a token from the live demo license. The request needs only the license key:
curl https://clavem.io/v1/licenses/validate \
-d license_key="S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8"
The response has the usual fields and a token string. The token has three parts, joined by dots: the prefix sgt1, a base64url payload and a base64url signature. Decoding the payload of the token I received on 19 November 2026 gives this:
{
"v": 1,
"lid": 1,
"pid": 1,
"kh": "7e0e4148136b6dae",
"status": "active",
"valid": true,
"email": "ada@example.com",
"iat": 1795126540,
"refresh_by": 1796336140
}
iat is the issue time in seconds since the Unix epoch: 19 November 2026, 22:15:40 UTC. refresh_by is 1796336140, which is 3 December 2026, 22:15:40 UTC. The difference is 1,209,600 seconds, exactly 14 days. A license with an end date also carries exp, and for a Stripe subscription that value includes three days of grace after the paid period. The demo license never expires, so it has no exp. The kh field is the first 16 hex characters of the SHA-256 of the normalized license key, which lets the app confirm the token belongs to the key the customer typed.
The signature is 64 bytes. I checked that in the same script that decoded the payload.
The seven checks, in order
- Split on dots. There must be exactly three parts, and the first must be
sgt1. - Decode the public key and the signature from base64url.
- Verify the Ed25519 signature over the ASCII text
sgt1.<payload>, using the first two parts exactly as received. If it fails, stop. - Decode the payload and parse the JSON.
- Check
vis 1,pidis your product id andvalidistrue. - If
expis present, check it is in the future. - Compare
refresh_bywith the current time. Before it, trust the token. After it, ask the server again.
Steps 3 and 5 do the work. A valid signature on a token for another product still has to be rejected, which is what the pid check is for.
Verify it yourself
The public key of the demo product is not published, so I cannot verify the live token here. Instead, this script creates a fresh Ed25519 key pair, mints a token in the same sgt1 format and verifies it with only the 32-byte public key. It runs on Node 18 and later. The full version is in the offline verification docs, which also have Swift, Rust, PHP and Python.
import { createPublicKey, verify } from 'node:crypto';
// The 12-byte prefix that wraps a raw Ed25519 public key as SPKI/DER.
const SPKI = Buffer.from('302a300506032b6570032100', 'hex');
export function verifyToken(token, publicKey) {
const p = token.split('.');
if (p.length !== 3 || p[0] !== 'sgt1') return null;
try {
const key = createPublicKey({
key: Buffer.concat([SPKI, Buffer.from(publicKey, 'base64url')]),
format: 'der',
type: 'spki',
});
const signed = Buffer.from(p[0] + '.' + p[1]);
if (!verify(null, signed, key, Buffer.from(p[2], 'base64url'))) return null;
return JSON.parse(Buffer.from(p[1], 'base64url').toString());
} catch {
return null; // malformed token or key
}
}
I minted tokens with iat set to the demo token’s value and ran the checks at different times. The output:
day 0 -> licensed
day 13 -> licensed
day 15 -> stale: ask the server again
subscription exp at day 5, checked day 6 -> expired (exp passed)
license disabled -> signed, but license is disabled
token for product 2 checked as product 1 -> wrong product or version
verify with another product key -> rejected
The signature check is the same in each case. What changes is the claims, and the app has to read them.
The four states an app must handle
| State | How you recognise it | What the app should do |
|---|---|---|
| Fresh | Signature verifies, pid matches, valid is true, no exp or exp in the future, refresh_by in the future. |
Run. Do not call the server unless you want a newer token. |
| Stale | Everything above, but refresh_by has passed. |
Call validate. If the call cannot be made, ask the buyer to connect once. |
| Expired or disabled | Signature verifies and valid is false, or exp has passed. |
Tell the buyer why. Keep the key, because a renewal can revive an expired license. |
| Invalid | Signature fails, malformed token, wrong pid or v. |
Treat as unlicensed. Discard the stored token and ask for the key. |
An expired license still produces a token. It verifies and says valid: false, so the app can say “your license has expired” offline instead of “something is wrong”.
Where to keep the token
Keep the license key and the token together, and store them where the operating system keeps per-user secrets: the Keychain on macOS, the Credential Manager or DPAPI on Windows, the Secret Service or a file with user-only permissions on Linux. The token is not a secret in the cryptographic sense, since it is signed and not encrypted. It still contains the buyer’s email address and it is the thing a person could copy to another computer, so there is no reason to leave it in a world-readable file.
Tampering with the stored file is already covered by the signature. Deleting it only makes the app fall back to the server, which asks the buyer for the key again if it also lost the stored key. You do not need to hide the file.
A test plan for your offline path
Most licensing bugs live in the paths that are hard to reach by hand. Run these seven before you ship, and keep the results with the release notes.
| Test | How to run it | Expected result |
|---|---|---|
| Online, valid license | Normal launch | Licensed, and a newer token is stored |
| Offline inside the window | Disconnect the network after one successful launch | Licensed from the stored token |
| Offline after the window | Mint a token with an old iat, or move the system clock forward 15 days |
Prompt to connect once |
| Edited payload | Change one character in the stored token | Treated as invalid, key requested |
| Another product’s token | Store a token with a different pid |
Treated as invalid |
| Rate limited or server down | Point the app at a local server that answers 429, then 503 | Falls back to the stored token, no lockout |
| Disabled license | Disable a test license in your dashboard, launch online | Told why, key kept |
Rows two to six need no real license: mint the tokens with a local key pair, as in the script above. The rate-limited row catches the mistake that does the most damage in practice: an app that treats any non-200 answer as “not licensed”.
Clock rollback
Everything above compares refresh_by with the system clock, and the user controls the system clock. Setting it back keeps a token fresh indefinitely. A cheap defence is to store the highest iat you have ever seen, and to treat a current time that is earlier than it as stale. My script printed yes: treat as stale for a clock three days after issue when the app had already seen a token from day 20. This does not stop a determined attacker. It stops the buyer who changed the date by accident or to save a trial.
What a token cannot tell you
Revocation after issue. If you disable a license today, a token issued yesterday still verifies until its refresh_by. You can shorten the window, which reaches offline devices sooner, but it also asks honest users on a plane to connect more often. Why sign license responses covers what signing does and does not buy.
Who holds the token. A token is not bound to a device. Compare iid or fp with what your app stored at activation if you want it to be.
Privacy. The payload is readable. Do not put tokens in analytics or crash reports.
Choosing a window
| Window | Revocation reaches offline devices in | Honest user offline for longer than the window |
|---|---|---|
| 1 day | At most 1 day | Prompted almost every day offline |
| 14 days | At most 14 days | Prompted after two weeks offline |
| 90 days | At most 90 days | Rarely prompted, slow revocation |
Match the window to how you sell. A subscription app that is used online anyway can use a short window. A tool that people use on air-gapped machines needs a longer one. Clavem fixes the window at 14 days. If you need a different one, enforce it in your app by comparing iat with your own limit instead of using refresh_by.
Doing this with Clavem
Every activate and validate answer includes a token, signed with the product’s Ed25519 key. Find the public key on the product page, or as public_key in GET /v1/admin/products. The token decoder shows the fields of any token you paste. Clavem does not provide an SDK. The code on the offline docs page is meant to be copied into your app.
Questions
Does an offline license check mean the license never needs the internet?
No. The token has a refresh deadline. Before it, the app trusts the token. After it, the app should ask the server again. The deadline is the price of being able to revoke a license.
Can a user fake an offline check by changing the system clock?
They can set the clock back to keep a token looking fresh. Store the highest issue time you have seen and treat a clock earlier than that as stale.
Is the token encrypted?
No. It is signed, not encrypted. Anyone holding it can read the payload, including the buyer's email address, so do not send tokens to third parties.