Clavem

Licensing offline-first apps: three policies for the 14-day window, compared

Clavem's signed token tells an app to check online again after 14 days. What the app does when it cannot is your policy, and for an offline-first product the strict default is usually wrong for perpetual licenses. Decide separately for perpetual and subscription licenses, and never delete a customer's data over a failed check.

What offline-first changes

Most licensing advice assumes a user with a network. An offline-first app, a note-taking tool, a local-first editor, a field data collector, a tool for photographers or sailors, assumes the opposite. People use it on planes, in tunnels and in buildings with no signal, and they chose it partly for that.

For these apps a license check that fails closed is a product defect. A paying customer locked out in the field will not be comforted by an explanation that the token window had ended.

What the token gives you

Every activate and validate response carries a signed token. The app verifies the signature with a public key it ships, and reads the payload. Two time fields control what offline means.

Claim Meaning Present for
refresh_by Issue time plus 14 days. After it, the app should validate online again Every token
exp When the license expires. For a subscription it includes three days of margin Licenses with an expiry
valid true for active and inactive, false for expired and disabled Every token

The documented check for “licensed” requires a good signature, the right product, valid: true, exp in the future if present, and refresh_by in the future. That last condition is the 14-day window. It is a default, not a law. The offline documentation says your app can keep trusting an expired window if you choose.

Three policies

I computed what each policy answers for two kinds of license across a range of days since the last online check. The tokens are idealized: one perpetual, one for a monthly subscription issued at the start of its period, so exp is 33 days out.

A. Strict. The documented default. Licensed only while both exp and refresh_by are in the future.

B. Trust a valid token indefinitely for perpetual licenses. Ignore refresh_by. Still honor exp and valid.

C. Thirty days of extra tolerance. Allow up to 30 days past refresh_by.

Perpetual license, no exp:

Days offline 1 10 14 15 30 34 60
A. Strict yes yes no no no no no
B. Trust indefinitely yes yes yes yes yes yes yes
C. 30 days past yes yes yes yes yes yes no

Monthly subscription, token issued at the start of the period:

Days offline 1 10 14 15 30 34 60
A. Strict yes yes no no no no no
B. Trust, still honoring exp yes yes yes yes yes no no
C. 30 days past yes yes yes yes yes no no

The subscription table shows something useful: for a subscription, exp ends access on day 33 under any policy, because that is the paid period plus the margin. A device offline longer than that must reconnect, and it may well have been renewed in the meantime. For that reason, a token that has run past exp while offline should display as “connect to check your license”, not as “expired”. The grace period article covers the timeline.

Choosing

Product Suggested policy Reason
Perpetual desktop or mobile app B The customer owns the license. Revocation of a refunded license reaches the app at its next online check, which is soon enough
Perpetual app with expensive abuse risk C A visible limit on how long a refunded license keeps working
Subscription app A or C exp bounds access in any case
Field tool used for weeks off-grid B for perpetual, a long C for subscription Tell customers how often to reconnect
Air-gapped installation A, with a documented routine The customer refreshes the token on a schedule

The cost of policy B is that a refunded or revoked license keeps working on a device that never reconnects. A device that never reconnects is also a device that never updates or syncs. Few customers will stay offline for good just to keep a refunded license. Do not design the experience of everyone else around them.

Edge cases

The first activation

Activation is an online call that creates a device seat. A brand-new install on a machine with no connection cannot activate. Say so in the interface: “Connect once to activate. After that the app works offline.” That is a single prompt and one short wait, and it is honest.

Air-gapped sites

A machine that can never connect can still run on a token. Call validate with only the license key on a connected machine. The response includes a signed token and uses no device seat. Carry the token across and let the app verify it locally. The token is not bound to a device, which is the trade-off: anyone who holds it can present it. Because a token is only good until refresh_by, the customer must repeat the routine, and you should document it.

Clocks

A customer can set the clock back to keep a token fresh, and a dead battery can set it forward or back by years. Store the highest iat you have seen in a verified token and treat a clock earlier than it as untrusted. If the clock looks wrong, say that in the message, because “license expired” would be the wrong diagnosis.

Vendor outage or disappearance

If the licensing service is unavailable, tokens on customers’ machines stay valid until their refresh_by. With policy B or C they last longer. If it disappeared for good, the customer data is not lost either: the dashboard exports licenses as CSV, and the License API uses a shape other services already implement. The signed token is what makes this possible, because the app can verify it with a public key and no server.

Design principles

  1. Fail soft. A license problem should reduce features, not delete or lock the user’s data.
  2. Keep read access. An expired license can still open and export what the customer made.
  3. Separate the states. Show needs-network differently from expired and from disabled.
  4. Do not sync license state. A token belongs to one device. Keep it out of the data that syncs between devices.
  5. Test with the network off. A real test is airplane mode and a changed system date.

Doing this with Clavem

The token, its 14-day window and the public key come with every product. The policy is a few lines in the app. Start from the verification code on the offline verification page and set the thresholds to match the table above. The launch flow in the quickstart shows how an app validates online first and falls back to the stored token.

Questions

How long does an offline license token stay valid?

A Clavem token carries a refresh time 14 days after it was issued, and licenses with an expiry also carry an expiry time. The documented checks require both to be in the future. Your app may choose to trust a validly signed token longer, which is a policy decision for you.

Can a customer activate on a machine that has no internet?

Activation is an online call. A machine with no network can use a signed token fetched elsewhere, because validating with only a license key returns a token and uses no device seat. The token is not bound to a device, so treat it as a convenience for air-gapped sites.

What happens to offline apps if the licensing service goes away?

Tokens already on customers' machines stay valid until their refresh time, and the app can keep trusting an expired window if you choose. Licenses can be exported as CSV from the dashboard at any time.