Offline Licensing

Licensing Features

Offline Activation

SDK 2.1.1 offline setup

Offline access needs a public key your application already trusts. A key stored beside a license token in an editable cache file cannot establish that trust. Earlier 1.x cache behavior has a confirmed trust weakness; use the migration below before relying on the SDK 2.1.1 offline cache. Use the language-specific installation command in the SDK references.

  1. Find your tenant slug in your application integration settings. While connected to your verified API origin, request GET /api/v1/{tenantSlug}/public-key. Take the returned publicKey: this is your tenant's ECDSA P-256 verification key.
  2. Put that public key in trusted application configuration distributed with your app. Never ship the private signing key. Stripe keys, Paddle tokens and Admin JWT keys are different credentials and cannot verify these license tokens.
  3. Configure the SDK's trusted public key list, an application-specific cache directory, and the same stable device ID on each launch. Pass the expected product ID when validating or activating. No configured trust keys means cached authorization is disabled; online license calls remain available.
  4. For automatic grace, make a successful online validate/activate call with an offline-capable license. SDK 2 requires a fresh signed proof containing the license-key SHA-256 and checked product. Activation fallback and node-locked validation also need signed evidence of an existing activation for that device. Validation never consumes a seat.
  5. For manual offline activation, generate a device token in Admin, then call the configured client's offline activation method. On later launches, call its offline validation method. Both verify against configured trust; every disk read verifies the original signed token.
  6. Test a genuine token, changed token, wrong signer, missing trust keys, wrong license, wrong product, wrong device and expired deadline before shipping your app.

Migration changes: .NET offline activation/validation are now instance methods; Go uses client methods and the /v2 module path; C++ persisted offline validation is now an instance method. Manual activation helpers no longer accept a public key argument. Raw signature verification still takes an explicit key and leaves key trust to the caller.

The new files contain only the original token and use separate _v2_ filenames with a full SHA-256 suffix. Legacy cache files are ignored. Original signed manual tokens can still verify with a trusted key, but product-pinned use needs a new token containing productId. Multiple approved keys support deliberate rotation; removing a compromised key requires an application or configuration update.

When connected, the optional server token-status check needs no Admin session. It checks the token tenant's signing-key status and any tracked revocation. Valid tokens issued independently with your exported signing key also work, but untracked tokens have no individual server revocation record. SDK 2.1.1 supports this check under tenant row-level security without an Admin session.

Offline verification cannot learn about revocation, device removal or a later payment change until reconnection. Previously issued proofs retain their signed deadline. Local clock manipulation and application patching remain outside this protection. Store payment-grace caps still apply. See the language-specific SDK references.

For Store subscriptions, newly generated offline tokens expire no later than paid-through plus the effective payment grace. Reconnect to obtain an updated signed token after renewal. Already-issued offline tokens retain their signed deadline while disconnected.

Offline activation lets customers activate a license key on a machine that has no internet access. Instead of calling the public API, the customer presents a signed offline token that was generated for their specific device by a Company Admin.

How it works

  1. Customer generates their hardware fingerprint (HWID) and sends it to you via email / support portal.
  2. Admin opens the license in PermitCore → scrolls to Offline Activation Tokens → clicks Generate Token.
  3. Admin enters the Device ID, optional device name, and how long the token should be valid (1–365 days).
  4. A signed token is shown once — admin copies and sends it to the customer.
  5. Customer's application calls ActivateOffline(token) in your SDK. The SDK verifies the ECDSA signature, expiry, and device binding, then stores the token locally.
  6. On every subsequent launch, the SDK verifies the cached token offline — no internet needed.
The offline token is verified using your tenant's ECDSA P-256 public key. The public key is available at GET /api/v1/{tenantSlug}/public-key — the SDK uses it for verification; distribute it in trusted application configuration before disconnecting. Distribute the trusted public key to an air-gapped machine before activation. Offline verification works only until the token expires; the machine cannot discover revocations while disconnected.

Step-by-step in the Admin Panel

Obtain the public verification key from the public API and generate the device token in Admin. Prepare both before disconnecting the customer machine.

1
Fetch your public verification key (once, or after rotation)
Call GET /api/v1/{tenantSlug}/public-key and keep the returned publicKey and kid with your application or offline package. The public verification key can verify signatures, not create them. Export Signing Key, available on every plan including Free, returns private signing material as well; keep that vendor recovery package private and distribute only the public verification key to customers.
2
Get the customer's Device ID
The customer's application calls the SDK's hardware-fingerprint helper (e.g. GetHardwareId()) and sends you the resulting string — by email, support ticket, or an in-app "Copy Device ID" button you build. This is the value the token gets bound to.
3
Generate the token
Open the customer's license: Licenses → [find the license] → View. Scroll to Offline Activation Tokens and click Generate Token. Paste the Device ID from step 2, optionally name the device (e.g. "Warehouse PC 3"), and choose how many days the token stays valid (1–365).
4
Copy the token — shown once
The signed pc_offline_v1.… string is displayed exactly once. Copy it now and send it to the customer alongside the public key from step 1 (not the token alone — the customer's app needs both to verify).
5
Customer activates offline
The customer's application calls the SDK's offline-activate function with the token and your public key (see the SDK code below). From then on it verifies the cached token locally on every launch — see "What the SDK does" below.
"Invalid signature" almost always means the wrong public key. Every downloadable SDK demo ships with a pre-filled sample public key and token pair purely to illustrate the fields — pasting a real token from your own tenant against that sample key will always fail signature verification, by design. Replace both fields with your own tenant's real public key (step 1 above) and a token generated for the actual device before testing.

Token format

Tokens have the format pc_offline_v1.<payload>.<signature>:

PartWhat it contains
pc_offline_v1Version prefix — validated first by the SDK
<payload>Base64URL-encoded JSON: tokenId, licenseKeyHash, deviceId, productName, expiresAt, …
<signature>Base64URL-encoded ECDSA P-256/SHA-256 signature over the UTF-8 bytes of the base64url payload string

What the SDK does

  1. Split on ., check prefix is pc_offline_v1
  2. Use an independently configured tenant public key originally obtained from /api/v1/{slug}/public-key
  3. Verify ECDSA signature — reject if invalid or tampered
  4. Check expiresAt > now — reject if expired
  5. Check deviceId matches local hardware fingerprint — reject if different machine
  6. Store token on disk — verified offline on every future launch
All eight official SDKs implement offline token verification natively — no manual crypto required in your app. The critical implementation detail every SDK matches exactly: the server signs with ECDSA P-256 / SHA-256, IEEE P1363 raw signature format (a 64-byte r‖s concatenation, not ASN.1 DER) over the UTF-8 bytes of the base64url payload string.
C# (.NET SDK)
// SDK 2.1.1; configure trusted keys before disconnecting.
using var client = new PermitCoreClient(new PermitCoreOptions {
    BaseUrl = "https://your-domain.com",
    TrustedPublicKeys = new[] { trustedTenantPublicKey },
    CacheDirectory = appCacheDirectory,
    DeviceId = hwid
});
var activated = client.ActivateOffline(offlineToken, expectedProductId: productId);
var cached = client.ValidateOffline(expectedProductId: productId);
Python (Python SDK)
# pip install cryptography  (lazy-imported — base client stays dependency-free)
client = PermitCoreClient("https://your-domain.com", trusted_public_keys=[trusted_public_key],
    cache_directory=app_cache_directory, device_id=hwid)
result = client.activate_offline(offline_token, expected_product_id=product_id)

# On every subsequent launch — no internet needed
result = client.validate_offline(expected_product_id=product_id)

The following Node.js and PHP examples assume clients configured with trusted public keys, cache directory and a stable device ID as explained above.

Node.js / TypeScript
const result = client.activateOffline(offlineToken, hwid, productId);

// On every subsequent launch — no internet needed
const result = client.validateOffline(hwid, productId);
PHP
$result = $client->activateOffline($offlineToken, $hwid, $productId);

// On every subsequent launch — no internet needed
$result = $client->validateOffline($hwid, $productId);
Java
OfflineTokenResult result = client.activateOffline(offlineToken, hwid, productId);

// On every subsequent launch — no internet needed
OfflineTokenResult result = client.validateOffline(hwid, productId);
C++
auto result = client.activate_offline(offline_token, hwid, product_id);

// On every subsequent launch — no internet needed
auto result = client.validate_offline(hwid, product_id);

Revoking a token

To revoke an offline token, go to the license detail page → Offline Activation Tokens → click the ban icon next to the token. The token is immediately marked as revoked in the database.

Revoking is soft enforcement: the SDK can optionally call POST /api/v1/offline/verify to check revocation status when online. Strictly offline deployments won't see revocations until the token naturally expires. Use short expiresInDays values (e.g. 30–90 days) for tighter control.

Design trade-off: Offline activation cannot be instantly revoked on an air-gapped machine — the token must expire. Set short validity periods (30–90 days) for sensitive deployments. For perpetual licenses, use annual renewal tokens.

Optional server-side verification

When the customer's machine has internet access, your SDK can also call the server to check for revocation:

Request: POST /api/v1/offline/verify
{
  "token": "pc_offline_v1.eyJ2ZXJzaW9uIjoxLCJ..."
}
Example response
{
  "isValid":     true,
  "tokenId":     "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "productName": "Acme Video Editor Pro",
  "deviceId":    "a3f8d2b1c9e4...",
  "expiresAt":   "2026-08-29T00:00:00Z",
  "message":     "Token valid."
}

Security properties

PropertyHow it's achieved
Tamper-proofECDSA P-256 signature — any modification invalidates the signature
Device-boundToken payload includes deviceId — SDK rejects tokens for other machines
Time-limitedexpiresAt checked by both SDK and server verify endpoint
RevocableTokenId stored server-side — checked via /offline/verify when online
Public key distributionPublic key is per-tenant, fetched once from /api/v1/{slug}/public-key