Clavem

Signed license token

A signed license token is a short piece of data, issued by a license server and signed with a private key, that an app can check with the matching public key to confirm a license is valid without calling the server again.

How it works

The app sends a license key to the licensing server. The server looks up the license and builds a small JSON payload that describes it: which product, what status, when it was issued. It signs that payload with the product’s private key and returns the result. The app verifies the signature with the public key it ships. If the check passes, the payload is exactly what the server wrote, so the app can trust it with no network call.

A real token, decoded

This request used the public demo license on 19 November 2026. Only validate was called.

curl https://clavem.io/v1/licenses/validate -d license_key=S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8

The response carries a token field in the form sgt1.<payload>.<signature>. Split on dots: sgt1 is the format prefix, the payload is base64url-encoded JSON, and the signature is 64 bytes, also base64url. The decoded payload of the token that came back:

{
  "v": 1,
  "lid": 1,
  "pid": 1,
  "kh": "7e0e4148136b6dae",
  "status": "active",
  "valid": true,
  "email": "ada@example.com",
  "iat": 1795126780,
  "refresh_by": 1796336380
}
Field Meaning
v Format version. Reject anything but 1.
lid, pid License id and product id. Check pid so a token from another product cannot be used.
kh First 16 hex characters of the SHA-256 of the normalized key, so the app can confirm the token belongs to the key typed.
status, valid Status at issue time. Expired and disabled licenses still get a token, with valid set to false.
iat Issued at, in Unix seconds: 2026-11-19 22:19:40 UTC.
refresh_by iat plus 14 days: 2026-12-03 22:19:40 UTC. After this the app should ask the server again.

iid, fp and exp appear when they apply: the activation instance id, the device fingerprint, and the expiry of a license that has one.

What a token cannot tell you

  • Revocation after issue. A token says what the license looked like when it was signed. If you disable the license tomorrow, today’s token still verifies until refresh_by.
  • A clock set backwards. An offline app trusts the system clock. Keep the highest iat you have seen and treat an earlier clock as stale.
  • Who holds it. A token is not bound to a device. Compare iid or fp with what the app stored at activation.
  • Secrecy. The payload is readable by anyone who has the token, including the buyer’s email address. Do not send tokens to third parties.

Signed token versus license key

A license key is a credential the buyer types. It has no meaning by itself; the server decides what it is worth. A signed token is the server’s statement about that key at one moment, protected by a digital signature so the app can check it alone. The app needs the key to ask the question and the token to keep the answer.

How Clavem handles it

Every activate and validate response includes a token, signed with Ed25519 using a key pair that belongs to the product. The public half is on the product page in the dashboard and safe to ship. Verification code for JavaScript, Swift, Rust, PHP and Python is in the offline verification guide, and the token decoder shows any token’s fields in the browser.

Questions

Can a customer edit the contents of a signed token?

They can read it, because the payload is only encoded, not encrypted. They cannot change it, because any edit makes the signature check fail.

Does a signed token replace the license key?

No. The key is what the customer types. The token is the server's signed answer about that key, and the app stores both.