Licensing SDK
Every self-hosted Vend product checks its licence through a small SDK — for Node.js, PHP and Python. All three share the same token format, error codes and cache rules. This page covers what a developer needs to wire one in.
The SDK packages are not on public package registries yet. Email support@vendsoftwares.com for access.
Two methods, two jobs
- check() never makes a network call. Run it on every request, in middleware. It reads the signed token from the local cache.
- validate() talks to the licence server. Run it once a day (cron, scheduler or a timer), or when
check()asks for it.
// On every request — never touches the network
let result = lic.check();
// Only when the grace window has run out or the clock looks wrong
if (!result.valid && result.requiresOnline) {
result = await lic.validate();
}
if (!result.valid) {
// e.g. E_LICENSE_EXPIRED → read-only mode; show result.message("en")
}
if (result.warning) {
// show a banner, but don't stop the user's work
}If the licence server can't be reached, the product keeps working on its cached token: a refresh is attempted after 24 hours, and a 72-hour grace window follows before going online becomes mandatory. The product stops only when the server clearly says the licence is not valid, or the grace window has fully run out.
Setup
Node.js
import path from "node:path";
import { VendLicense } from "@vend/license-node";
export const lic = new VendLicense({
productCode: "CRM",
publicKeys: { v1: "MCowBQYDK2VwAyEA..." }, // in your product's code
licenseKey: process.env.VEND_LICENSE_KEY, // entered by the customer
cachePath: path.join(__dirname, "../storage/vend/license.cache"),
instanceId: process.env.APP_DOMAIN, // required in Node
});Set instanceId (the customer's domain). The SDK deliberately does not read the request's Host header. Create one instance per process.
PHP
use Vend\License\VendLicense;
$lic = new VendLicense([
'product_code' => 'CRM',
'public_keys' => ['v1' => 'MCowBQYDK2VwAyEA...'], // in your product's code
'license_key' => $_ENV['VEND_LICENSE_KEY'], // entered by the customer
'cache_path' => __DIR__ . '/../storage/vend/license.cache',
]);Python
import os
from vend_license import VendLicense
lic = VendLicense(
product_code="CRM",
public_keys={"v1": "MCowBQYDK2VwAyEA..."}, # in your product's code
license_key=os.environ["VEND_LICENSE_KEY"], # entered by the customer
cache_path="/srv/crm/var/vend/license.cache",
instance_id="crm.agency-client.com",
)Put the public key in your product's source code, not in the customer's .env. The key is public, not secret — but if the customer controls it, they can point the product at a server of their own that approves everything.
Signing keys and rotation
The licence server writes a key ID (kid) into every token. The SDK verifies a token only with the key that has that ID — there is no “try every key” fallback, and a token with an unknown key ID is rejected.
publicKeys: {
v1: "MCowBQYDK2VwAyEA...", // current key — keep until it is retired on the server
v2: "MCowBQYDK2VwAyEA...", // next key — ship it before the server switches
},The older single publicKey option still works but ignores the key ID, so a product using it stops working once the server moves to a new key. New products should use publicKeys (public_keys in PHP and Python).
What the SDK guards against
- A fake licence server. Tokens are signed with Ed25519 and checked against the key built into the product — including tokens fresh from the server, before they are cached.
- Copying a token to another server. Each token names the instance it was issued for, and the SDK checks it.
- Turning the clock back. A clock that moves back more than five minutes forces an online check. Smaller drift is ignored, since cheap hosting is often out of sync.
Feature flags and limits
result.can("whatsapp"); // boolean
result.feature("max_users"); // raw value
result.withinLimit("max_users", userCount); // -1 means unlimitedIn Python the limit check is within_limit(). A value of -1 means unlimited on both the server and the SDK.
Error codes
Messages come from the server in English and Hindi — call result.message("en") or result.message("hi") instead of hard-coding text.
| Reason | Meaning | What the product should do |
|---|---|---|
E_NOT_ACTIVATED | This install has not been activated | Show the setup wizard |
E_OFFLINE_EXPIRED | The offline grace window has ended | Call validate() |
E_CLOCK_TAMPER | The server clock moved backwards | Call validate() |
E_TOKEN_INVALID | Signature or instance did not match | Call validate() |
E_UNREACHABLE | Could not reach the licence server and nothing is cached | Retry later |
E_NO_LICENSE_KEY | No licence key in the configuration | Ask for the key |
E_NO_INSTANCE_ID | No instance ID configured (Node) | Fix the configuration |
E_LICENSE_EXPIRED | The licence has expired | Read-only mode — don't delete data |
E_LICENSE_SUSPENDED | Suspended, usually a billing issue | Send to billing |
E_LICENSE_REVOKED | Revoked permanently | Block, with a support link |
E_ACTIVATION_LIMIT | Already active on other servers | List result.activations |
E_PARENT_INACTIVE | The white-label parent licence is inactive | Ask them to contact their agency |
E_PENDING_APPROVAL / E_LICENSE_REJECTED | Waiting on, or refused, approval | Wait, or contact support |
E_INVALID_FORMAT / E_INVALID_CHECKSUM / E_LICENSE_NOT_FOUND / E_PRODUCT_MISMATCH | The key is wrong | Ask for the key again |
Cache file
The SDK keeps a small cache file at the path you give it. Keep it outside the public web folder. The cache is disposable: if it is deleted or corrupted, the SDK recovers by going online. The licence key itself belongs in your product's own configuration, not in the cache.