Skip to content

Developer docs

Licence protocol

Three POST endpoints that your installed product calls. Each takes the same four JSON fields, and nothing else is ever sent.

Also in the app: terminal.deventitle.com/docs · Machine-readable spec: openapi.json (OpenAPI 3.1)

The basics

  • Base URL: https://terminal.deventitle.com/api/v1
  • Every call is POST with a JSON body of exactly four fields, over HTTPS.
  • Licence answers are always HTTP 200, whether the licence is valid or not. Read valid and show message.
  • No data from inside your product is ever sent.

The four fields

FieldExampleNotes
license_keyACME-7KQ2M-…As the buyer typed it; spaces and case don't matter
productacme-crmThe product slug on DevEntitle
domaincrm.buyer.comThe site's host, or a stable device ID for products counted per machine
version1.4.2The installed version

POST /api/v1/activate

Checks the key and records this domain (or device) against the licence.

Request
curl -X POST https://terminal.deventitle.com/api/v1/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "ACME-7KQ2M-X9PTR-4HWBN-C8ZVD",
    "product": "acme-crm",
    "domain": "crm.buyer.com",
    "version": "1.4.2"
  }'
200 OK · valid
{
  "valid": true,
  "message": "Licence active.",
  "buyer": "Buyer Ltd",
  "license_type": "Single site",
  "supported_until": "2027-10-15T23:59:59Z"
}

When the licence can’t be used here, valid is false and the message says why and what to do:

200 OK · limit reached
{
  "valid": false,
  "message": "This licence is already used on its maximum of 1 site: crm.old.com. Remove it there under Updates & licence, or contact support."
}

POST /api/v1/deactivate

Frees this domain or device, for example when the buyer is moving to a new server. It always answers {"ok": true}, so it can’t be used to test whether keys exist.

Request
curl -X POST https://terminal.deventitle.com/api/v1/deactivate \
  -H "Content-Type: application/json" \
  -d '{"license_key": "ACME-7KQ2M-X9PTR-4HWBN-C8ZVD", "product": "acme-crm", "domain": "crm.buyer.com", "version": "1.4.2"}'
200 OK
{"ok": true}

POST /api/v1/updates

Asks for the newest release this licence can see.

Request
curl -X POST https://terminal.deventitle.com/api/v1/updates \
  -H "Content-Type: application/json" \
  -d '{"license_key": "ACME-7KQ2M-X9PTR-4HWBN-C8ZVD", "product": "acme-crm", "domain": "crm.buyer.com", "version": "1.4.2"}'
200 OK
{
  "license": {
    "valid": true,
    "message": "Licence active.",
    "supported_until": "2027-10-15T23:59:59Z"
  },
  "latest": {
    "version": "1.5.0",
    "channel": "stable",
    "notes": "## What's new …",
    "released_at": "2026-11-01T09:30:00Z",
    "size": 36168558,
    "sha256": "…",
    "signature": "…",
    "download_url": "https://terminal.deventitle.com/dl/…"
  }
}
  • latest is the newest published release on the licence’s channel, or null when there is none.
  • signature and download_url are present only when the licence may download that release. Otherwise latest.message says why (for example, support ended before it came out).
  • Download links expire after 30 minutes. Ask again just before installing.
  • Always check the SHA-256 and the signature before installing. See checking an update.

Messages your product shows

Display message as it is. These are the cases:

CaseWhat the buyer sees
Active“Licence active.” Or that support has ended; the licence stays valid.
Not recognisedA typo or an unknown key.
Not valid for this productNothing more is revealed.
Limit reachedNames the other site(s) and what to do: remove it there, or contact support.
Suspended, revoked, refunded or expiredWith the company's reason and support email.
New version after support ended“Version X came out after your support ended. Renew support to download it; your installed version keeps working.”

How activations count

  • Per website domain for web apps, or per machine ID for desktop apps and CLI tools. You choose on the product.
  • Development hosts never count: localhost, *.test, *.local, *.localhost, *.example, *.invalid, example.com/.net/.org, and private and reserved IP addresses.
  • A limit of 0 means unlimited. A single licence can override its type’s limit.
  • Buyers move a licence themselves: deactivate in the product, or Remove the old site in the buyer portal.
  • Activation IP addresses are shown shortened and deleted after 90 days.

Keys look like ACME-7KQ2M-X9PTR-4HWBN-C8ZVD: a prefix per licence type, then four groups of five characters without easily confused characters (about 98 bits of randomness).

Support periods

  • Each licence has a support end date, or lifetime. When support ends, the licence stays valid. The product shows that support has ended and the buyer can renew for help and updates.
  • After support ends the buyer can still download every release published before support ended. Newer releases show their version and notes, with a message to renew and no download link.
  • A licence type can let updates continue after support ends (only help stops).
  • Renewal moves support forward from today or from the current end date, whichever is later. The key stays the same.

Buyers are never cut off

If a company is suspended or a product retired, licences already issued keep answering.

Rules for products

These rules are required

  1. Never disable features because a licence is invalid or the server can’t be reached. A licence unlocks updates, downloads and support only. Show the message.
  2. Only a 5xx answer is a server problem: say “could not be reached, try later” and keep working.
  3. HTTP 429 means too many checks in a minute (60 per IP, 20 per key). Check on demand or once a day, not on every page view.
  4. Send only the four fields.

HTTP status codes

StatusMeaningWhat your product does
200A licence answer (valid or not)Show message; hold back updates if not valid
429Too many checks this minuteWait and try later; keep working
5xx or no answerServer problemSay it could not be reached; keep working