Skip to content

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 unlimited

In 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.

ReasonMeaningWhat the product should do
E_NOT_ACTIVATEDThis install has not been activatedShow the setup wizard
E_OFFLINE_EXPIREDThe offline grace window has endedCall validate()
E_CLOCK_TAMPERThe server clock moved backwardsCall validate()
E_TOKEN_INVALIDSignature or instance did not matchCall validate()
E_UNREACHABLECould not reach the licence server and nothing is cachedRetry later
E_NO_LICENSE_KEYNo licence key in the configurationAsk for the key
E_NO_INSTANCE_IDNo instance ID configured (Node)Fix the configuration
E_LICENSE_EXPIREDThe licence has expiredRead-only mode — don't delete data
E_LICENSE_SUSPENDEDSuspended, usually a billing issueSend to billing
E_LICENSE_REVOKEDRevoked permanentlyBlock, with a support link
E_ACTIVATION_LIMITAlready active on other serversList result.activations
E_PARENT_INACTIVEThe white-label parent licence is inactiveAsk them to contact their agency
E_PENDING_APPROVAL / E_LICENSE_REJECTEDWaiting on, or refused, approvalWait, or contact support
E_INVALID_FORMAT / E_INVALID_CHECKSUM / E_LICENSE_NOT_FOUND / E_PRODUCT_MISMATCHThe key is wrongAsk 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.