Vendor API reference

Use the Vendor API from your backend to manage licences, such as issuing keys after payment or resetting a customer's HWID. API keys have only the scopes you grant. Runtime protections and account settings require a dashboard sign-in.

i

BASE is https://licentry.cc. Every path below is relative to it. This is the vendor management API; the client-facing session endpoints your app ships with live in the integration docs.

Authentication

Create an API key in your dashboard under API keys. Each key is shown once, is tied to your account, and carries only the scopes you grant it. Send it as a bearer token:

Authorization header
Authorization: Bearer lk_live_9fA2x…

Keys look like lk_live_ followed by 40 characters. Only a hash is stored, so a leaked database does not expose usable keys. Rotate or revoke a key from the dashboard at any time; a revoked key stops working immediately.

!

API keys are for server-to-server use. Never ship one in a client binary or web page. The build token and session endpoints, not an API key, are what your distributed app uses.

Create a vendor-wide key or bind it to one product using productId at creation, or the product's settings page. A product-bound key receives 404 for another product's licences and 403 product_scope when issuing for another product; /products lists only its bound product. Use a separate product-bound key for each integration to limit the effect of a leak.

Scopes

Grant each key the least it needs. A key that only resets HWIDs cannot issue licences or read billing.

ScopeGrants
licenses.readList and read licences.
licenses.issueGenerate new licence keys.
licenses.manageRevoke, suspend, resume, extend, delete. Implies read.
devices.readList devices bound to a licence.
devices.resetHWID reset and unbind a device. Implies device read.
sessions.readList runtime sessions on a licence.
sessions.killTerminate runtime sessions. Implies session read.
products.readList products.
products.writeCreate and edit products. Implies read.
analytics.readRead account details. It gates the vendor block of GET /v1/vendor/me: email, company name, status, plan id, billing status, current period end and creation date. It does not gate usage counts: the usage block is returned to every key, so a key can check its own quota. Your dashboard lists it as Read account details under Account.
*Full access. Use sparingly.

A call missing the required scope returns 403 insufficient_scope with the scope it needed. Account-management actions (minting keys, rotating signing keys, billing) are never available to an API key; they require a dashboard sign-in.

Account

GET/v1/vendor/me

Your account, current plan, and usage against plan limits. Also returns your per-account JWKS URLs.

200 OK · abridged
{
  "vendor": { "id": "…", "email": "[email protected]", "planId": "studio", "status": "active" },
  "plan": { "id": "studio", "maxActiveLicenses": 5000, "maxProducts": 15, "maxApiKeys": 20 },
  "usage": { "activeLicenses": 812, "products": 3, "apiKeys": 4 },
  "jwks": {
    "offlineGrace": "/v1/vendor/keys/…/offline-grace-jwks",
    "responseSig":  "/v1/vendor/keys/…/response-sig-jwks"
  },
  "session": { "impersonated": false }
}

The example abbreviates plan and usage, which contain additional counters. Without analytics.read, the vendor block contains only { "id": "…" }, not the email or other account details shown. All keys receive the remaining response blocks, including usage.

session.impersonated is true during a Licentry staff support session. The audit trail records the staff identity; this field reports only whether impersonation is active. API keys always receive false.

Products

A product is the app you license. Its slug is stamped onto every key and is what your client sends to activate.

GET/v1/vendor/products

List your products. Scope products.read.

POST/v1/vendor/products

Create a product. Scope products.write.

shell
curl -sS -X POST "$BASE/v1/vendor/products" \
  -H "Authorization: Bearer $LICENTRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "desktop-app", "name": "Desktop App", "maxDevicesPerKey": 2 }'
PATCH/v1/vendor/products/:id

Update a product. Scope products.write, which covers name and archived and nothing else on its own.

!

API keys cannot change the runtime protections below. Only an account owner or admin signed into the dashboard can set them. An API key with products.write, including one with *, receives 403 policy_change_forbidden with the attempted fields listed. The scope permits renaming and archiving products without granting permission to weaken their protections.

The table lists the product controls and their defaults. For client requirements and setup instructions, see switch the protections on. A product nobody has configured enforces none of these.

FieldDefaultWhat it does
requireBuildTokenfalseRequire the x-licentry-build header on session calls. Without enforcement, a modified release can omit its revoked token and continue.
requireDpopfalseRequire a proof-of-possession key to create or renew a session. A copied installation folder then needs the original private key. Update clients before enabling this, since existing unbound sessions cannot renew.
requireDpopBodyfalseRequire a bh claim on DPoP proofs for heartbeat and refresh. This binds the proof to the request body as well as the method, URL and token, preventing a proxy from changing the body under a genuine proof. Release a client that sends bh first; see request body binding.
maxConcurrentSessions1 from the deployment defaultHow many live sessions one licence may hold at once, 1 to 20, or null to inherit the deployment default. The oldest is evicted when a new activation exceeds it.
maxDevicesPerKey1How many devices one licence may bind, 1 to 100. Unlike the concurrency cap this refuses, with 403 too_many_devices.
engineParamsnullAn object up to 16 KB, sealed at rest under your account's key and never returned to anyone, including you. Delivered to your client inside the session, alongside the reserved _session and _mark blocks. Editing it advances _session.epoch. Pass null to clear it. For what belongs in it, see the worked example.
engineSecretPinnedfalseNot yet functional. The flag is not passed to the secret derivation, so enabling it has no effect and reports no error. _session.secret still changes on every heartbeat for every product. Read it from each newly decrypted blob instead of caching it at activation.
payloadKeynullA key of 16 to 4096 characters, sealed at rest and delivered only in a live session's engine blob to decrypt your files. It cannot be read back after saving, so retain your own copy. Saving a new key increments _payload.version. Pass null to clear it.
payloadRequiresDpopfalseRelease the payload key only to a proof-of-possession-bound session. Decryption then requires its device private key, which a copied installation folder should not contain. Clients must support _payload.sealed before enabling this; eligible sessions never receive _payload.key.
vendorResponseSigningfalseSign this product's runtime responses with your account's own key instead of the platform's shared one. Your client has to pin your JWKS first, and there is no overlap signature, so the order matters: the rollout is written out in the integration guide.
minProtocolVersion0The oldest client protocol version this product opens a session for. 0 accepts everything. Read at activate and nowhere else, so raising it never cuts a session already running, and it is what the client declares about itself rather than something the server measures.

Set the fields above on the product page in the dashboard. With an API key, this route renames or archives a product:

shell
curl -sS -X PATCH "$BASE/v1/vendor/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $LICENTRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Tools Pro" }'

Client builds

A build token identifies a client release so you can revoke it after a leak. It is plaintext in the binary, is not a secret and does not authenticate the client.

Creating and revoking tokens requires an account owner or admin seat. Developer seats cannot perform these actions.

GET/v1/vendor/client-builds

List your registered builds and their tokens.

POST/v1/vendor/client-builds

Register a release and receive its token. Pass productId to restrict it to one product and select that product's response-signing key. A product-bound token produces the same kid for valid, invalid and unknown licence keys; without that binding, an unknown key can receive a response signed by the deployment key instead. Each account may have 500 live builds. Revoke releases you no longer distribute.

shell
curl -sS -X POST "$BASE/v1/vendor/client-builds" \
  -H "Authorization: Bearer $LICENTRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Desktop App 4.2.0", "version": "4.2.0", "productId": "$PRODUCT_ID" }'
POST/v1/vendor/client-builds/:id/revoke

Cut off a release. Every session route then answers 426 to that token. This only binds while the product has requireBuildToken on, because otherwise the revoked binary can drop the header and carry on.

Licences

POST/v1/vendor/licenses

Issue one or more keys for a product. Scope licenses.issue. The plaintext keys are returned once; only hashes are stored.

shell · issue 3 one-year keys
curl -sS -X POST "$BASE/v1/vendor/licenses" \
  -H "Authorization: Bearer $LICENTRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product": "desktop-app", "count": 3, "validDays": 365, "note": "order #1024" }'
201 Created
{
  "keys": [
    { "id": "…", "licenseKey": "aB3xK9m-7Qp2n-M4kL8z-Xy1Wq9r", "product": "desktop-app", "validUntil": "2027-07-24T…" }
  ],
  "notice": "Store these keys now; only their hashes are kept."
}
GET/v1/vendor/licenses

List licences. Scope licenses.read. Query: product, status (active/suspended/revoked), limit, offset.

GET/v1/vendor/licenses/:id

One licence. Scope licenses.read.

POST/v1/vendor/licenses/:id/revoke
POST/v1/vendor/licenses/:id/suspend
POST/v1/vendor/licenses/:id/resume
POST/v1/vendor/licenses/:id/extend

Lifecycle actions. Scope licenses.manage. Revoke and suspend invalidate live sessions on the next heartbeat; resume credits the paused time back onto the expiry; extend takes { "days": n } (negative to shorten).

DELETE/v1/vendor/licenses/:id

Permanently delete a licence row. Scope licenses.manage.

Devices & HWID

GET/v1/vendor/licenses/:id/devices

List the machines bound to a licence, with first/last IP and last-seen. Scope devices.read.

POST/v1/vendor/licenses/:id/hwid-reset

Clear every bound device so the licence can activate on a fresh machine. Scope devices.reset. This bumps the revocation version and ends live sessions on the old machine at its next heartbeat, the same as the dashboard's HWID reset button.

shell · reset a customer's HWID
curl -sS -X POST "$BASE/v1/vendor/licenses/$LICENSE_ID/hwid-reset" \
  -H "Authorization: Bearer $LICENTRY_KEY"
DELETE/v1/vendor/licenses/:id/devices/:deviceId

Unbind a single device without resetting the whole licence. Scope devices.reset.

Runtime sessions

Sessions record activations of a key, including the device, IP address and heartbeat activity. Use them to review current use or end one machine's session without changing the rest of the licence.

GET/v1/vendor/licenses/:id/sessions

Newest first, with per-session state (live, idle, expired, evicted, killed, ended), device hash, IP with country when available, heartbeat count and expiry. ?active=1 filters to sessions that can still heartbeat. Scope sessions.read.

POST/v1/vendor/licenses/:id/sessions/:sessionId/kill

Terminate one session. The client receives session_killed on its next heartbeat and aborts instead of silently re-activating. Devices stay bound. Scope sessions.kill.

POST/v1/vendor/licenses/:id/sessions/kill-all

Terminate every live session on the licence in one call. Returns the count. Scope sessions.kill.

GET/v1/vendor/licenses/:id/insights

Returns the licence and product, bound devices, session history, validation and network statistics, and sharing indicators with severities and raw counts. The verdict is none, possible or strong. This read does not enforce a decision; the dashboard licence console uses the same data. Scope licenses.read.

Evidence is computed on each read, not on a timer. This call can emit sharing.suspected, so poll licences you need to monitor if you want alerts without opening them manually. The hardening guide lists each indicator and threshold after sign-in. Keeping those thresholds off the public page limits information that could help someone avoid detection.

Public JWKS

Every account has its own offline-grace and response-signing keys, so the offline entitlement tokens your app honours, and the runtime responses it verifies once you opt in, are signed with keys only you hold. The same isolation applies to licence keys at rest: each account's keys are hashed under its own sealed pepper, never a shared secret, so nothing outside your tenant can verify or forge them. These endpoints are public (no auth) and return a standard JWK set.

GET/v1/vendor/keys/:vendorId/offline-grace-jwks
GET/v1/vendor/keys/:vendorId/response-sig-jwks

Find your vendorId and exact URLs under Signing keys in the dashboard or in the jwks block of GET /v1/vendor/me. Fetch the keys at build time and pin them in the client. Rotation publishes a new public key alongside the current one without using it to sign; release a client that pins both before promoting it. An unconfigured key returns 404 with offline_grace_not_configured or response_sig_not_configured.

For offline grace, pin your account's keys and select by the JWT header's kid. If the account key is unavailable, the response omits offlineGraceJwt; it never falls back to the platform key. GET /v1/sess/offline-grace-jwks serves only the deployment key for licences without a vendor account and cannot verify your account's tokens.

Response signing uses the deployment keys from GET /v1/sess/response-sig-jwks while vendorResponseSigning is off, its default. Enabling it switches the product's responses, including refusals, to your account key without a platform overlap signature. Register build tokens with productId so valid, invalid and unknown licence keys receive the same kid. Pin both sets during the transition, then remove deployment keys when installed clients no longer need them. Follow the rollout and key-unavailability guidance under vendorResponseSigning.

Discord integration

Studio accounts can connect one Discord server. Generate a link code on the dashboard's Discord page and run /link-account in that server to enable the following bot features.

  • A redeem panel. The bot posts a message with a button; customers press it, paste their key, and their Discord account is stored on that licence. Title, copy, colours, button, image and the confirmation message are all editable on the dashboard, with a live preview. Post it with /panel post, and optionally grant a customer role on every redeem.
  • Key commands for your staff. /keys gen (with product autocomplete), /keys info by key, licence id or member, /keys reset for HWID resets, /keys ban, /keys unban and /keys revoke. Admin commands need Manage Server; replies containing keys are always private.
  • Activity logs. Key events (redeems, new devices, blocked activations, hardware mismatches, resets, bans) stream to a channel via /logs set, to a Discord webhook you paste into the dashboard, or both. Pick exactly which events on the dashboard.

Every command is checked server side against your account and plan, so a leaked bot or a spoofed guild cannot touch keys that are not yours. The Discord user id and username stored on a redeemed key show up in the licence console and in GET /v1/vendor/licenses responses as a discord object.

Webhooks

Licentry sends signed JSON events to your registered HTTPS endpoints. Licence events cover activation, device changes, blocked attempts and sharing verdicts, so your backend can respond without polling /licenses. Account events report activity such as unfamiliar sign-ins and newly created API keys.

Registering an endpoint

Register up to five endpoints under Webhooks in the dashboard. Each has a separate signing secret and event selection. An empty selection subscribes to every event, including future additions. Webhooks require an active plan or trial.

Use the final public HTTPS URL. Before every delivery, Licentry resolves it and rejects loopback, link-local and private addresses. Redirects are not followed: a 3xx is a failed delivery, preventing a redirect from changing the destination after address validation.

i

Registering and re-pointing endpoints is dashboard-only. An API key with * can read your endpoints and the delivery log, but no key can create one or change its URL, so a leaked key cannot redirect your event stream.

Events

EventFires when
license.activatedA key completes activation and a runtime session starts.
device.boundA key binds a hardware slot it had not used before.
activation.blockedA key hits its device cap and activation is refused.
session.mismatchA live session shows up from different hardware and is cut.
session.killedRuntime sessions are killed from the dashboard, API or bot.
sharing.suspectedA licence's evidence is computed and comes out at a strong verdict, which happens when the licence insights are read from the dashboard or the API. Rate limited per licence so one shared key cannot flood your endpoint. Treat it as evidence worth reading, not as proof: open the licence and judge from the timeline before you revoke anything.
license.createdNew licence keys are created.
license.redeemedA customer ties a key to their Discord account.
license.unlinkedA Discord account is detached from a key.
license.suspendedA key is put on hold.
license.resumedA suspended key is reinstated.
license.revokedA key is permanently killed.
license.extendedTime is added to or removed from a key.
device.resetBound devices are cleared so a key can move machines.
tamper.reportedYour client reports tampering through POST /v1/sess/tamper-report. The payload carries what the client sent, unverified, and says whether a screenshot existed; the screenshot itself is never in a webhook payload.
loader.launchedA copy of the Licentry desktop loader issued for one of your licences reports a launch, with the machine details it collected, unverified.
account.login_new_locationA sign in to your Licentry account succeeds from a country, or from a browser and operating system, that the account has not been used from in the last 180 days. Sign in history is kept for 180 days and then removed, so a device you have not touched since last year counts as new again. The first sign in after this event was introduced establishes the baseline and never alerts.
account.twofa_changedTwo factor authentication on your account is turned on or off, or its recovery codes are replaced.
account.member_addedSomebody is invited to help manage your account. The invite is a second way to sign in to the same tenant.
account.api_key_createdAn API key is minted from your dashboard. Carries the key prefix, never the key.
account.webhook_updatedAn endpoint is registered, or an existing one has its URL, event list or enabled state changed. Delivered to the endpoints that were registered before the change: if somebody re-points your URL, the address they pointed away from is the one that gets told, and it carries both the old URL and the new one.

Route the five account events to someone who can review them. A successful sign-in from a new country may be legitimate; only your team can confirm that.

Account events go only to webhook endpoints, never the Discord log feed. This keeps owner sign-in locations, second-factor changes and API-key activity out of a channel that may be readable by the whole team.

The dashboard's Send test button sends webhook.test directly to the endpoint. It bypasses the queue and does not appear in the delivery log.

The payload

Every delivery is a POST with the same envelope. id is the delivery id, type is the event, and data carries whatever fits the event: typically the licence id, the product slug, a masked key and who did it.

POST to your endpoint
{
  "id": "9d1f7c0a-3b6e-4f21-9f2c-0f6a8b41d5e7",
  "type": "license.activated",
  "createdAt": "2026-07-24T18:04:11.220Z",
  "vendorId": "b3c1…",
  "data": {
    "licenseId": "7f2e…",
    "product": "desktop-app",
    "keyMasked": "aB3x…Wq9r"
  }
}

Verifying the signature

Three headers ride on every POST. Check the signature before you trust the body.

headers
Licentry-Signature: t=1753380251,v1=8f14e45fceea167a5a36dedd4bea2543…
Licentry-Event:     license.activated
Licentry-Delivery:  9d1f7c0a-3b6e-4f21-9f2c-0f6a8b41d5e7

v1 is HMAC-SHA256, hex encoded, over the string t + "." + raw body, keyed with that endpoint's secret. The timestamp is inside the signed material, so a captured delivery cannot be replayed later under a fresh header. Sign the bytes exactly as they arrived: re-serializing the JSON changes them and the signature will not match.

node
import crypto from 'crypto';

function verify(rawBody, header, secret) {
    const m = /^t=(\d+),v1=([a-f0-9]{64})$/.exec((header || '').trim());
    if (!m) return false;
    if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;

    const expected = crypto.createHmac('sha256', secret)
        .update(m[1] + '.' + rawBody)
        .digest('hex');
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}
python
import hashlib, hmac, re, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.fullmatch(r"t=(\d+),v1=([a-f0-9]{64})", (header or "").strip())
    if not m:
        return False
    if abs(time.time() - int(m.group(1))) > 300:
        return False

    signed = m.group(1).encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, m.group(2))
!

Reject anything whose t is more than 5 minutes off your clock, and always compare with a constant-time compare. Dedupe on Licentry-Delivery: a retry reuses the same delivery id, so a receiver that acknowledged late can see the same event twice.

Answer 2xx as soon as the signature checks out, then do the real work in a queue. We give up on a request after 10 seconds and count it as a failure, and anything outside 200 to 299 is a failure too.

Retries and auto-disable

Each delivery gets up to eight attempts. After failures, the retry delays are 15 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, covering roughly 20 hours. After the final failure, the delivery remains in the log for manual replay.

After 40 consecutive failures, an endpoint is disabled and its dashboard card shows the reason. Fix the receiver, send a test and re-enable it to clear the failure counter. Events are not queued for disabled endpoints.

Reading the delivery log

GET/v1/vendor/webhooks/deliveries

Every attempt we made, newest first, with status (pending, delivered, failed), attempt count, the HTTP code and error we got back, how long it took, and when the next retry is due. Query: webhookId, limit (default 50, max 200). Scope *. The log keeps 30 days.

GET/v1/vendor/webhooks

Your endpoints and the event catalog. Scope *. Signing secrets are never in this response; they are readable only from a dashboard sign-in.

Errors & limits

Errors are JSON with an error code and, where useful, a human message.

StatusCodeMeaning
401unauthorizedMissing or invalid API key.
403insufficient_scopeKey lacks the required scope (returned in required).
403vendor_suspendedAccount suspended; settle billing to restore access.
403plan_limitA plan quota (licences, products, keys) was reached.
404not_foundNo such resource under your account.
429rate_limitedBack off; honour the RateLimit-* headers.