Offline Licensing
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.
- 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 returnedpublicKey: this is your tenant's ECDSA P-256 verification key. - 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.
- 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.
- 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.
- 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.
- 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
- Customer generates their hardware fingerprint (HWID) and sends it to you via email / support portal.
- Admin opens the license in PermitCore → scrolls to Offline Activation Tokens → clicks Generate Token.
- Admin enters the Device ID, optional device name, and how long the token should be valid (1–365 days).
- A signed token is shown once — admin copies and sends it to the customer.
- Customer's application calls
ActivateOffline(token)in your SDK. The SDK verifies the ECDSA signature, expiry, and device binding, then stores the token locally. - On every subsequent launch, the SDK verifies the cached token offline — no internet needed.
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.
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.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.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).Token format
Tokens have the format pc_offline_v1.<payload>.<signature>:
| Part | What it contains |
|---|---|
pc_offline_v1 | Version 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
- Split on
., check prefix ispc_offline_v1 - Use an independently configured tenant public key originally obtained from
/api/v1/{slug}/public-key - Verify ECDSA signature — reject if invalid or tampered
- Check
expiresAt> now — reject if expired - Check
deviceIdmatches local hardware fingerprint — reject if different machine - Store token on disk — verified offline on every future launch
// 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);# 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.
const result = client.activateOffline(offlineToken, hwid, productId); // On every subsequent launch — no internet needed const result = client.validateOffline(hwid, productId);
$result = $client->activateOffline($offlineToken, $hwid, $productId);
// On every subsequent launch — no internet needed
$result = $client->validateOffline($hwid, $productId);OfflineTokenResult result = client.activateOffline(offlineToken, hwid, productId);
// On every subsequent launch — no internet needed
OfflineTokenResult result = client.validateOffline(hwid, productId);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.
Optional server-side verification
When the customer's machine has internet access, your SDK can also call the server to check for revocation:
{
"token": "pc_offline_v1.eyJ2ZXJzaW9uIjoxLCJ..."
}{
"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
| Property | How it's achieved |
|---|---|
| Tamper-proof | ECDSA P-256 signature — any modification invalidates the signature |
| Device-bound | Token payload includes deviceId — SDK rejects tokens for other machines |
| Time-limited | expiresAt checked by both SDK and server verify endpoint |
| Revocable | TokenId stored server-side — checked via /offline/verify when online |
| Public key distribution | Public key is per-tenant, fetched once from /api/v1/{slug}/public-key |