Offline license validation with JWT tokens

Most software licensing is built around a single assumption: the user is online. Call an API, validate the license, let them in. It works until it doesn't.

Desktop apps, tools used in restricted environments, and anything that runs locally will eventually face the offline problem. Requiring a network round-trip on every launch is fragile: it breaks on planes, corporate firewalls, and unreliable connections. Users get locked out of software they paid for, and support tickets pile up.

We built offline license verification into Keyforge to fix this. The approach uses JSON Web Tokens (JWTs) as signed license tokens that your app can verify locally, with no server involved.

How signed license tokens work

A JWT is a small, self-contained data object with three parts: a header, a payload, and a cryptographic signature. The signature is created with a private key that only Keyforge holds. Your application verifies it using the corresponding public key, which you can get from the dashboard.

Because the signature covers the payload, a user cannot modify the token contents without breaking verification. If the check passes, you know the token is genuine and unaltered.

In Keyforge, a license token payload includes the license key, product, expiration date, and device identifier. Your app checks those claims locally at startup, no network required.

Fetching the first token

The one moment that does require connectivity is the initial license activation. When a user activates their license, your app calls the activation API:

curl -X POST https://keyforge.dev/api/v1/public/licenses/activate \
  -H "Content-Type: application/json" \
  -d '{
    "licenseKey": "ABCDE-ABCDE-ABCDE-ABCDE-ABCDE",
    "deviceIdentifier": "some_device_id",
    "deviceName": "My device",
    "productId": "p_123456"
  }'

A successful response includes a signed token JWT. Store it in local device storage. From this point on, your app can go offline and still validate the license.

Validating offline

Use any JWT library for your language and verify these claims on every validation:

• exp: the token has not expired.
• product.id: matches your product.
• device.identifier: matches the device running the app.

That is the complete validation flow. No network call, no latency, no failure from lost connectivity.

Refreshing tokens

Tokens have an expiration date by design: it ensures a revoked license eventually stops working even without connectivity. When the app does have a connection, use the license token API to fetch a fresh token in the background:

curl -X POST https://keyforge.dev/api/v1/public/licenses/token \
  -H "Content-Type: application/json" \
  -d '{
    "licenseKey": "ABCDE-ABCDE-ABCDE-ABCDE-ABCDE",
    "deviceIdentifier": "some_device_id",
    "productId": "p_123456"
  }'

Replace the stored token with the new one. If the user is offline and the stored token has expired, we recommend giving them a reasonable grace period before restricting access. Cutting someone off precisely at the expiry timestamp is a frustrating experience when they simply have not had a connection to refresh.

Why JWTs work well for this

JWT-based offline licensing has a few properties that make it worth building on.

It works in any language. JWT libraries exist for every major platform and language. Whether your app is built in Rust, Swift, C#, or Python, you can verify tokens without any Keyforge-specific SDK.

It is tamper-proof. A user cannot forge a valid token without access to the private key, which never leaves our servers. Only the public key is needed on the device.

It degrades gracefully. When the token is expired and the user is offline, you can still inspect the payload to decide what limited access makes sense, rather than showing a generic "license invalid" error.

Setting it up

You can create a license token configuration in the dashboard. For more in depth information and a step-by-step guide, see the Keyforge documentation.