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_dayson 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"
}
]
}currentsigns every new token.nextsigns nothing yet: it takes over at the next rotation, so software that embeds it keeps verifying new tokens after one.previoussigned tokens before a rotation and signs nothing more. It stays in the set for 365 days, the longest a token it signed can live, untilexpires_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 claimsOn 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
- 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. - Your software keeps the token, and unlocks
featureswhile a check passes. - While online, it asks your server to refresh the token once a day, and to check the license with
verifyLicensewhen you want the latest status at once. - Offline, it checks the token it holds. Once the token expires, it asks the customer to go online.