Skip to content

Verify licenses offline

Hand your software a signed token when a device activates, and let it check the license with no network, against your store's public keys.

Updated

A check through verifyLicense needs your server, and your server needs the network. For the times your software runs without either, such as on a plane or behind a firewall, every activation also answers a license token: a short string your store signs, which your software checks on its own against your store’s public keys. This guide reads the token, verifies it in a few languages, and keeps it fresh. It builds on Verify licenses, which sets up activations.

Get a token

POST /products/{product}/licenses/activate answers a token with every device it counts, and token_expires_at, when it stops verifying. Your server passes both to your software, which keeps them:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/activate' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
  "instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47",
  "name": "Studio Mac"
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/activate', {
  body: {
    "key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
    "instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47",
    "name": "Studio Mac"
  },
});

Answers 200, abridged:

{
  "activation": {
    "id": "6b5a4938-2716-4f05-8e4d-3c2b1a0f9e8d",
    "license_id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
    "name": "Studio Mac",
    "status": "active",
    "created_at": "2026-09-02T09:20:00.000Z",
    "activated_at": "2026-09-02T09:20:00.000Z",
    "last_seen_at": "2026-09-02T09:20:00.000Z",
    "deactivated_at": null,
    "deactivated_by": null
  },
  "activations": {
    "count": 2,
    "limit": 3
  },
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6IjBjMWIyYTM5LTQ4NTctNGY2ZS05ZDhjLTdiNmE1ZjRlM2QyYyJ9.eyJzdG9yZSI6IjVkNGMzYjJhLTE5MDgtNGY3ZS04ZDZjLTViNGEzOTI4MTcwNiIsInByb2R1Y3QiOiIzZTlkMWY2Yi03MmE0LTRjNTgtYjBlMy05YTZmMmQ4NGMxYjciLCJsaWNlbnNlIjoiOGM3YjZhNTktNDgzNy00MjYxLTlmMGUtMWQyYzNiNGE1OTY4IiwiYWN0aXZhdGlvbiI6IjZiNWE0OTM4LTI3MTYtNGYwNS04ZTRkLTNjMmIxYTBmOWU4ZCIsInRpZXJfcmFuayI6MiwiZmVhdHVyZXMiOlsic3luYyIsImV4cG9ydCJdLCJpYXQiOjE3ODgzNDA4MDAsImV4cCI6MTc5MDkzMjgwMH0.lTzRaa-n_zLU3KaU5wiBzNNOaBLXhoxTSrWrB5rlU3X-sE217UZYZiHAi5y9pQqo1syzW9FvTApZfNMlWvpHDA",
  "token_expires_at": "2026-10-02T09:20:00.000Z"
}

The token is a JSON Web Token signed with Ed25519 (alg EdDSA), and its kid header names the key that signed it. Its claims say what the device may unlock:

Claim What it holds
store Your store’s id.
product The software product’s id. Check it, so a token for another of your products never unlocks this one.
license The license’s id, as the API and webhooks name it. The token never carries the key.
activation The device’s activation id.
tier_rank The rank of the tier the customer’s access opens, null for access with no tier.
features That tier’s features, as a check answers them.
iat When it was issued, in seconds since 1970.
exp When it stops verifying, in seconds since 1970.

A token is only issued for an active license, so it never needs a status: holding a valid one means the license was active when it was issued, on the device it names.

When it expires

exp is the earliest of:

  • the product’s offline window: settings.software.offline_days on the product (1 to 365 days), 30 days when unset;
  • when the grant the tier comes from ends, so a token never claims a tier the customer no longer holds;
  • when all of the customer’s access ends.

A token can’t be taken back once issued: a refund, a revoke or a disabled license shows at the next online check or refresh, not before the token expires. Pick the offline window as the longest your software may run on a license you can no longer vouch for.

Refresh it

While the device is online, your server swaps the token for a fresh one with POST /products/{product}/licenses/token, for a device the license counts:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/token' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
  "instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47"
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/token', {
  body: {
    "key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
    "instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47"
  },
});

Answers 200, abridged:

{
  "activation": {
    "id": "6b5a4938-2716-4f05-8e4d-3c2b1a0f9e8d",
    "license_id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
    "name": "Studio Mac",
    "status": "active",
    "created_at": "2026-09-02T09:20:00.000Z",
    "activated_at": "2026-09-02T09:20:00.000Z",
    "last_seen_at": "2026-09-02T09:20:00.000Z",
    "deactivated_at": null,
    "deactivated_by": null
  },
  "activations": {
    "count": 2,
    "limit": 3
  },
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6IjBjMWIyYTM5LTQ4NTctNGY2ZS05ZDhjLTdiNmE1ZjRlM2QyYyJ9.eyJzdG9yZSI6IjVkNGMzYjJhLTE5MDgtNGY3ZS04ZDZjLTViNGEzOTI4MTcwNiIsInByb2R1Y3QiOiIzZTlkMWY2Yi03MmE0LTRjNTgtYjBlMy05YTZmMmQ4NGMxYjciLCJsaWNlbnNlIjoiOGM3YjZhNTktNDgzNy00MjYxLTlmMGUtMWQyYzNiNGE1OTY4IiwiYWN0aXZhdGlvbiI6IjZiNWE0OTM4LTI3MTYtNGYwNS04ZTRkLTNjMmIxYTBmOWU4ZCIsInRpZXJfcmFuayI6MiwiZmVhdHVyZXMiOlsic3luYyIsImV4cG9ydCJdLCJpYXQiOjE3ODgzNDA4MDAsImV4cCI6MTc5MDkzMjgwMH0.lTzRaa-n_zLU3KaU5wiBzNNOaBLXhoxTSrWrB5rlU3X-sE217UZYZiHAi5y9pQqo1syzW9FvTApZfNMlWvpHDA",
  "token_expires_at": "2026-10-02T09:20:00.000Z"
}

A refresh stamps the device seen, as a check naming it does. A license that isn’t active answers 409 conflict on status, and a device it doesn’t count (never activated, freed, or gone inactive) answers 404 not_found with the kind activation: activate the device again. Refresh well before token_expires_at, such as once a day, so a device that goes offline holds a token for most of the window. A refresh takes customer:read; activating takes customer:write.

Embed your public keys

Your software checks tokens against your store’s public keys, a JSON Web Key Set. GET /license_signing_keys lists them, with customer:read, and the merchant app shows the set to copy under Settings, License keys:

curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/license_signing_keys' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/license_signing_keys');

Answers 200, abridged:

{
  "keys": [
    {
      "kid": "0c1b2a39-4857-4f6e-9d8c-7b6a5f4e3d2c",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
      "alg": "EdDSA",
      "use": "sig",
      "status": "current",
      "created_at": "2026-08-14T10:00:00.000Z",
      "expires_at": null
    },
    {
      "kid": "7d6c5b4a-3928-4170-8f6e-5d4c3b2a1908",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "PUAXw-hDiVqStwqnTRt-vJyYLM8uxJaMwM1V8Sr0Zgw",
      "alg": "EdDSA",
      "use": "sig",
      "created_at": "2026-08-14T10:00:00.000Z",
      "expires_at": null,
      "status": "next"
    }
  ]
}
  • current signs every new token.
  • next signs nothing yet: it takes over at the next rotation, so software that embeds it keeps verifying new tokens after one.
  • previous signed tokens before a rotation and signs nothing more. It stays in the set for 365 days, the longest a token it signed can live, until expires_at.

Your store gets its keys when the first device activates, or when you create them in the merchant app or rotate an empty set. Ship the whole set in your software, kid, x and the rest, and update it with each release. The private keys never leave Sherpo, and are stored encrypted.

The same set is public on the customer API, with your publishable key, for software that fetches the set while online and keeps it for later.

Rotate the keys

POST /license_signing_keys/rotate promotes next to sign, publishes a new next and keeps the old key as previous. Software that embedded the set before the rotation keeps verifying, since it already holds the key that now signs; ship the new set before the next rotation. Pass current as { "id": "<kid>" }, the key that signs as you last read it (null for a store with no keys yet), so a retried call answers 409 conflict on revision, its current the key that signs now, instead of rotating twice.

If a key may have leaked, rotate with retire_previous, which drops every key that no longer signs from the published set at once, so a set fetched from then on refuses tokens they signed. Software that embeds a set keeps trusting what it embeds: ship an update without the leaked key, and until then its tokens, forged ones included, still verify there. Software that embeds only retired keys stops accepting new tokens until it’s updated.

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/license_signing_keys/rotate' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "current": {
    "id": "0c1b2a39-4857-4f6e-9d8c-7b6a5f4e3d2c"
  },
  "retire_previous": false
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/license_signing_keys/rotate', {
  body: {
    "current": {
      "id": "0c1b2a39-4857-4f6e-9d8c-7b6a5f4e3d2c"
    },
    "retire_previous": false
  },
});

Answers 200, abridged:

{
  "keys": [
    {
      "kid": "7d6c5b4a-3928-4170-8f6e-5d4c3b2a1908",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "PUAXw-hDiVqStwqnTRt-vJyYLM8uxJaMwM1V8Sr0Zgw",
      "alg": "EdDSA",
      "use": "sig",
      "created_at": "2026-08-14T10:00:00.000Z",
      "expires_at": null,
      "status": "current"
    },
    {
      "kid": "a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "Jb6Xr8rL0f8Mv2ZQm0Oq6t3dK1Yb7nS4hW9pE2uC5aI",
      "alg": "EdDSA",
      "use": "sig",
      "status": "next",
      "created_at": "2026-11-03T08:00:00.000Z",
      "expires_at": null
    },
    {
      "kid": "0c1b2a39-4857-4f6e-9d8c-7b6a5f4e3d2c",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
      "alg": "EdDSA",
      "use": "sig",
      "status": "previous",
      "created_at": "2026-08-14T10:00:00.000Z",
      "expires_at": "2027-11-03T08:00:00.000Z"
    }
  ]
}

Rotating takes customer:write.

Verify a token

Each check below takes the token, the key set your software embeds and your product’s id, and answers the claims, or nothing when the token is malformed, signed by a key the set doesn’t hold, signed wrongly, for another product, or expired. Each uses the platform’s own Ed25519, with no JSON Web Token library.

On Web Crypto: Node.js 20 and later, Deno, Bun, Electron and current browsers.

// Checks an offline license token against the key set your app embeds, as of `now`
// (seconds). Answers its claims, or null for a token to refuse; a key set that isn't
// one, or a runtime without Ed25519, throws instead, so it never refuses everyone quietly.
async function verifyLicenseToken(token, keySet, product, now = Date.now() / 1000) {
  const decode = (part) =>
    Uint8Array.from(atob(part.replaceAll('-', '+').replaceAll('_', '/')), (c) => c.charCodeAt(0));
  const object = (part) => {
    const value = JSON.parse(new TextDecoder().decode(decode(part)));
    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
  };
  const parts = token.split('.');
  if (parts.length !== 3) return null;
  const [head, body, signature] = parts;
  let header, claims, signed;
  try {
    header = object(head);
    claims = object(body);
    signed = decode(signature);
  } catch {
    // Not base64url or not JSON: never a token to trust.
    return null;
  }
  if (header?.alg !== 'EdDSA' || claims === null) return null;
  const jwk = keySet.keys.find((key) => key.kid === header.kid);
  if (jwk === undefined) return null;
  const key = await crypto.subtle.importKey(
    'jwk',
    { kty: 'OKP', crv: 'Ed25519', x: jwk.x },
    { name: 'Ed25519' },
    false,
    ['verify'],
  );
  const data = new TextEncoder().encode(`${head}.${body}`);
  if (!(await crypto.subtle.verify('Ed25519', key, signed, data))) return null;
  if (claims.product !== product || typeof claims.exp !== 'number' || claims.exp <= now) return null;
  return claims;
}

On the cryptography package (pip install cryptography).

import base64, json, time
from typing import Optional
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

def verify_license_token(token: str, key_set: dict, product: str, now: Optional[float] = None) -> Optional[dict]:
    """Checks an offline license token against the key set your app embeds. Answers its claims, or None to refuse it."""
    def decode(part: str) -> bytes:
        return base64.urlsafe_b64decode(part + "=" * (-len(part) % 4))
    parts = token.split(".")
    if len(parts) != 3:
        return None
    head, body, signature = parts
    try:
        header, claims, signed = json.loads(decode(head)), json.loads(decode(body)), decode(signature)
    except ValueError:
        # Not base64url or not JSON: never a token to trust.
        return None
    if not isinstance(header, dict) or not isinstance(claims, dict) or header.get("alg") != "EdDSA":
        return None
    jwk = next((key for key in key_set["keys"] if key.get("kid") == header.get("kid")), None)
    if jwk is None:
        return None
    try:
        Ed25519PublicKey.from_public_bytes(decode(jwk["x"])).verify(signed, f"{head}.{body}".encode())
    except InvalidSignature:
        return None
    exp = claims.get("exp")
    if claims.get("product") != product or not isinstance(exp, int) or exp <= (time.time() if now is None else now):
        return None
    return claims

On the standard library.

package license

import (
	"crypto/ed25519"
	"encoding/base64"
	"encoding/json"
	"errors"
	"strings"
	"time"
)

// Claims is what an offline license token says.
type Claims struct {
	Store      string   `json:"store"`
	Product    string   `json:"product"`
	License    string   `json:"license"`
	Activation string   `json:"activation"`
	TierRank   *int     `json:"tier_rank"`
	Features   []string `json:"features"`
	IssuedAt   int64    `json:"iat"`
	ExpiresAt  int64    `json:"exp"`
}

// KeySet is the JSON Web Key Set your app embeds.
type KeySet struct {
	Keys []struct {
		Kid string `json:"kid"`
		X   string `json:"x"`
	} `json:"keys"`
}

// VerifyLicenseToken checks an offline license token against the key set as of now.
func VerifyLicenseToken(token string, keys KeySet, product string, now time.Time) (*Claims, error) {
	parts := strings.Split(token, ".")
	if len(parts) != 3 {
		return nil, errors.New("license: not a token")
	}
	decode := base64.RawURLEncoding.DecodeString
	head, err := decode(parts[0])
	if err != nil {
		return nil, err
	}
	var header struct {
		Alg string `json:"alg"`
		Kid string `json:"kid"`
	}
	if err := json.Unmarshal(head, &header); err != nil {
		return nil, err
	}
	if header.Alg != "EdDSA" {
		return nil, errors.New("license: not an EdDSA token")
	}
	var public ed25519.PublicKey
	for _, key := range keys.Keys {
		if key.Kid == header.Kid {
			if public, err = decode(key.X); err != nil {
				return nil, err
			}
		}
	}
	if len(public) != ed25519.PublicKeySize {
		return nil, errors.New("license: signed by a key the set does not hold")
	}
	signature, err := decode(parts[2])
	if err != nil {
		return nil, err
	}
	if !ed25519.Verify(public, []byte(parts[0]+"."+parts[1]), signature) {
		return nil, errors.New("license: bad signature")
	}
	body, err := decode(parts[1])
	if err != nil {
		return nil, err
	}
	var claims Claims
	if err := json.Unmarshal(body, &claims); err != nil {
		return nil, err
	}
	if claims.Product != product {
		return nil, errors.New("license: another product's token")
	}
	if claims.ExpiresAt <= now.Unix() {
		return nil, errors.New("license: expired")
	}
	return &claims, nil
}

On CryptoKit, on macOS 10.15, iOS 13 and later.

import CryptoKit
import Foundation

/// What an offline license token says.
struct LicenseClaims: Decodable {
    let store: String
    let product: String
    let license: String
    let activation: String
    let tierRank: Int?
    let features: [String]
    let iat: Int
    let exp: Int

    enum CodingKeys: String, CodingKey {
        case store, product, license, activation, features, iat, exp
        case tierRank = "tier_rank"
    }
}

/// The JSON Web Key Set your app embeds.
struct LicenseKeySet: Decodable {
    struct Key: Decodable {
        let kid: String
        let x: String
    }
    let keys: [Key]
}

/// Checks an offline license token against the key set as of `now`; nil means refuse it.
func verifyLicenseToken(_ token: String, keySet: LicenseKeySet, product: String, now: Date = Date()) -> LicenseClaims? {
    func decode(_ part: Substring) -> Data? {
        var text = part.replacingOccurrences(of: "-", with: "+").replacingOccurrences(of: "_", with: "/")
        text += String(repeating: "=", count: (4 - text.count % 4) % 4)
        return Data(base64Encoded: text)
    }
    struct Header: Decodable {
        let alg: String
        let kid: String
    }
    let parts = token.split(separator: ".", omittingEmptySubsequences: false)
    guard parts.count == 3,
          let headData = decode(parts[0]),
          let header = try? JSONDecoder().decode(Header.self, from: headData),
          header.alg == "EdDSA",
          let jwk = keySet.keys.first(where: { $0.kid == header.kid }),
          let raw = decode(Substring(jwk.x)),
          let key = try? Curve25519.Signing.PublicKey(rawRepresentation: raw),
          let signature = decode(parts[2]),
          key.isValidSignature(signature, for: Data("\(parts[0]).\(parts[1])".utf8)),
          let body = decode(parts[1]),
          let claims = try? JSONDecoder().decode(LicenseClaims.self, from: body),
          claims.product == product,
          claims.exp > Int(now.timeIntervalSince1970)
    else { return nil }
    return claims
}

Read the clock your software trusts as now: a user who winds their clock back stretches a token, so keep the latest time your software has seen and refuse a token while the clock reads earlier than it.

Put it together

  1. On first run, your software sends the key the customer typed and its device id to your server, which activates the device and answers the token.
  2. Your software keeps the token, and unlocks features while a check passes.
  3. While online, it asks your server to refresh the token once a day, and to check the license with verifyLicense when you want the latest status at once.
  4. Offline, it checks the token it holds. Once the token expires, it asks the customer to go online.

Type to search…

↑↓ navigate↵ selectEsc close