Automate licensing from your own backend.

The Vendor API is how your systems talk to Licentry: issue keys when an order is paid, reset a customer's HWID from your support panel, suspend on a chargeback. Everything the dashboard does, your code can do, scoped to exactly what each key is allowed to touch.

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

Scopes

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

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

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

{
  "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 }
}

Both blocks are abridged: plan and usage carry more counters than shown. The vendor block is the one to check against your key's scopes, because a key without analytics.read receives { "id": "…" } and nothing else there. The email in the sample is not sent to such a key. Everything else on this response, including usage, goes to every key.

session.impersonated is true only when Licentry staff are signed into your account through a support session, and it is a boolean rather than a name because whichever of us it is, is our business and lives in the audit trail. An API key always sees false.

Products

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

List your products. Scope products.read.

Create a product. Scope products.write.

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 }'

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

Each field below is one line here and a control on the product page. What your client has to do differently for each one, and the mistake people actually make, is in the integration guide under switch the protections on. A product nobody has configured enforces none of these.

curl -sS -X PATCH "$BASE/v1/vendor/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $LICENTRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "requireBuildToken": true,
        "requireDpop": true,
        "maxConcurrentSessions": 1,
        "engineParams": { "tableSeed": "…", "assetKeyId": 7 }
      }'

Client builds

A build token identifies one release of your client. It is not a secret, it ships inside the binary as plaintext, and it does not authenticate anything. Treat it as a revocable version number: registering each release gives you a way to cut one off after it leaks.

Minting and revoking build tokens is admin work, so these routes need an account owner or an admin seat, not a developer seat.

List your registered builds and their tokens.

Register a release and get its token back. Pass productId to pin the token to one product, so a token lifted from one binary cannot act on another. Pinning also decides which key signs the response: with it, every answer on that product carries the same kid whether the licence key was good, bad or never issued at all, and without it a key that does not resolve is answered under the deployment key instead of yours. Accounts are capped at 500 live builds; revoke the releases you no longer ship.

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" }'

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

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

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" }'

{
  "keys": [
    { "id": "…", "licenseKey": "aB3xK9m-7Qp2n-M4kL8z-Xy1Wq9r", "product": "desktop-app", "validUntil": "2027-07-24T…" }
  ],
  "notice": "Store these keys now; only their hashes are kept."
}

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

One licence. Scope licenses.read.

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

Permanently delete a licence row. Scope licenses.manage.

Devices & HWID

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

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, exactly like the dashboard button and your support team's most common request.

curl -sS -X POST "$BASE/v1/vendor/licenses/$LICENSE_ID/hwid-reset" \
  -H "Authorization: Bearer $LICENTRY_KEY"

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

Runtime sessions

Sessions are live activations of a key: which machine, from which IP, heartbeating when. Use them to see who is running your software right now and to pull the plug on a single machine without touching the rest of the licence.

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.

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.

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

The full picture for one licence: the licence and its product, bound devices, session history, validation and network stats, plus a key-sharing analysis with named indicators, a severity on each, raw counts, and a verdict of none, possible or strong. Nothing in it enforces anything. This is what powers the licence console in the dashboard. Scope licenses.read.

The evidence is computed when this endpoint is called, not on a timer, so a licence nobody reads produces no verdict. That also makes this the call that emits sharing.suspected: poll it on the licences you care about if you want the alert without opening them by hand. Which indicators exist, what each one counts and the level each fires at are on the hardening guide in your dashboard rather than in this public reference, because a shared key is worth a lot more to the person sharing it once they know exactly where the lines are.

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.

Find your vendorId and the exact URLs on the Signing keys page of your dashboard, or in the jwks block of GET /v1/vendor/me. Pin these in your client, or fetch them once at build time and cache them. Rotating from the dashboard publishes the new public key here beside the current one, and nothing is signed with it until you promote it. That gap is the window in which to ship a build that pins both. A 404 means the key is not configured for your account yet, offline_grace_not_configured or response_sig_not_configured.

Offline grace: pin your own key. A licence belonging to a vendor account is signed with that account's key and there is no fallback, so if your key cannot be used the offlineGraceJwt field is simply absent rather than signed with the platform key. GET /v1/sess/offline-grace-jwks serves the deployment key, which signs only licences that belong to no vendor account, so verifying your own tokens against it fails every time. Select the verifier from the kid in the JWT header.

Response signing: which key to pin depends on one switch. vendorResponseSigning is off by default, and while it is off your product's responses are signed with the deployment key from GET /v1/sess/response-sig-jwks. Turn it on and every response for that product, refusals included, is signed with your account's key from the endpoint above, with no platform overlap signature riding along. Pass productId when you register a build token, so the same kid arrives on an approval, on a refusal, and on an answer for a key that was never issued. Pin both sets in the release that spans the change, then drop the deployment keys once nothing in the field still needs them. The full order, and what happens if your key is ever unavailable, is under vendorResponseSigning in the integration guide.

Discord integration

Studio accounts can wire their Discord server straight into their keys. You connect exactly one server: generate a link code on the Discord page of the dashboard, run /link-account in your server, done. From there the Licentry bot gives you three things.

• 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, colors, 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

Register an HTTPS endpoint and Licentry posts every key event to it as signed JSON, seconds after it happens. Activations, device binds, blocked activations, sharing verdicts, the whole key lifecycle. Your backend stops polling /licenses on a timer and starts reacting. A second, smaller group covers your own Licentry account rather than your customers, so a sign in from an unfamiliar country or a newly minted API key reaches you rather than only us.

Registering an endpoint

Endpoints live on the Webhooks page of your dashboard. Up to five per account, each with its own signing secret and its own list of events. Subscribe to nothing and the endpoint gets everything, including events added after you set it up. Webhooks need an active plan or a running trial.

The URL has to be public HTTPS. We resolve it before every delivery and refuse loopback, link-local and private address space, so a webhook can never be pointed back at our own network. Redirects are not followed either: a 3xx counts as a failed delivery, because following it would re-target the request after the safety check ran. Point the endpoint at its final URL.

Events

The last five describe your Licentry account rather than your customers, and they are the ones worth wiring to something that pages a human. Nobody else can tell us that a sign in from a new country was not you.

They reach your webhook endpoints only. We keep them off the Discord log feed on purpose: that channel is usually readable by the people you work with, and where the account owner signs in from, when the second factor changes and who minted an API key are not things to publish to a room that may contain the person the alert is about.

The Send test button on the dashboard posts one extra type, webhook.test, straight to the endpoint. It skips the queue and never lands in the delivery log, so use it to prove the plumbing works without waiting for a real event.

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.

{
  "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.

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.

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]));
}

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))

Retries and auto-disable

A delivery gets eight attempts in total. After the first one fails we wait 15 seconds, then 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. That is roughly 20 hours of cover, enough to ride out an overnight outage on your side. After the last attempt the delivery is marked failed and stays in the log, where you can replay it by hand.

An endpoint that fails 40 times in a row is switched off automatically, so one dead URL cannot generate deliveries forever. The dashboard shows the reason on the endpoint card. Fix the receiver, send a test, then switch it back on; enabling clears the failure counter. Events that happen while an endpoint is off are not queued for it.

Reading the delivery log

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.

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.