Clavem

Documentation

API reference

The License API your app calls, the management API your backend calls, and the releases endpoint for update checks.

Examples for validate and the not-found errors were captured from the running API with the demo license. The other examples show the shape of the response with sample values. Tokens are shortened.

Conventions

  • Base URL: https://clavem.io. HTTPS only.
  • The License API takes POST requests with a JSON body (Content-Type: application/json) or a form body (application/x-www-form-urlencoded). It needs no authentication: the license key is the credential.
  • Responses are JSON. The HTTP status carries the outcome, and the body repeats it as a boolean (activated, valid or deactivated) with an error that is null or a sentence you can show.
  • Keys are trimmed and matched without regard to case, up to 256 characters. Keys Clavem generates also forgive the usual misreadings: I and L read as 1, O as 0, U as V. Imported keys, such as Lemon Squeezy UUIDs, match as written, lower-cased.
  • Times are ISO 8601 in UTC. Ids in the License API are numbers, except instance.id, which is a UUID string.

License API

The three endpoints share paths, parameters and response shapes with the Lemon Squeezy License API. Clavem adds token to responses, and accepts fingerprint on activation.

POST /v1/licenses/activate

Ties a license key to one device. Call it once per device.

Parameters

NameTypeDescription
license_keystring, requiredThe customer's key.
instance_namestring, requiredA name for the device, up to 120 characters. Shown to the customer on the device page and to you in the dashboard.
fingerprintstring, optionalA stable identifier for the device, up to 200 characters. Activating again with a fingerprint already active on this license returns that seat, with its name updated, instead of using another. Send a hash, not a raw hardware id.

Request

curl
curl https://clavem.io/v1/licenses/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "YOUR-LICENSE-KEY",
    "instance_name": "Ada'"'"'s MacBook Pro",
    "fingerprint": "9f2c1e0b7a"
  }'

Response

Response200 OK
{
  "activated": true,
  "error": null,
  "license_key": {
    "id": 305,
    "status": "active",
    "key": "S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8",
    "activation_limit": 3,
    "activation_usage": 2,
    "created_at": "2026-11-18T23:08:58.988Z",
    "expires_at": null,
    "test_mode": false
  },
  "instance": {
    "id": "47596ad9-a811-4ebf-ac8a-03fc7b6d2a17",
    "name": "Ada's MacBook Pro",
    "created_at": "2026-11-19T09:12:41.207Z"
  },
  "meta": {
    "store_id": 79,
    "order_id": null,
    "order_item_id": 305,
    "product_id": 75,
    "product_name": "Inkwell",
    "variant_id": 75,
    "variant_name": "Default",
    "customer_id": 69,
    "customer_name": "Ada Lovelace",
    "customer_email": "ada@example.com"
  },
  "token": "sgt1.eyJ2IjoxLCJsaWQiOjMwNSwi…"
}

The first activation moves an inactive license to active. Disabled and expired licenses are refused before the device limit is checked. The token carries the new instance.id as iid, and the fingerprint as fp. Keep the instance.id: validate and deactivate need it.

Errors

StatuserrorCause
400instance_name: Invalid input: expected string, received undefinedA parameter is missing or malformed. The message starts with the parameter name.
400This license key has been disabled.Status disabled. The body includes license_key and meta.
400This license key has expired.Status expired. The body includes license_key and meta.
400This license key has reached the activation limit.Every seat is in use and the fingerprint, if any, matches none of them. The body includes license_key and meta.
404license_key not found.No such key.
429Too many requests. Try again in a minute.See rate limits.
503A generic messageTemporary failure on our side. Retry-After: 5.
Activation limit reached400 Bad Request
{
  "activated": false,
  "error": "This license key has reached the activation limit.",
  "license_key": { "id": 305, "status": "active", "activation_limit": 3, "activation_usage": 3, … },
  "meta": { … }
}
Missing parameter400 Bad Request
{
  "activated": false,
  "error": "instance_name: Invalid input: expected string, received undefined"
}

POST /v1/licenses/validate

Reports the license's current status. Call it at every launch.

Parameters

NameTypeDescription
license_keystring, requiredThe customer's key.
instance_idstring, optionalThe instance.id from activation. When given, the license must be active on that instance, the response includes it, and the token carries it as iid. Validation also records the time this device was last seen.

Request

curl
curl https://clavem.io/v1/licenses/validate \
  -d license_key="S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8" \
  -d instance_id="47596ad9-a811-4ebf-ac8a-03fc7b6d2a17"

Response

Response200 OK
{
  "valid": true,
  "error": null,
  "license_key": {
    "id": 305,
    "status": "active",
    "key": "S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8",
    "activation_limit": 3,
    "activation_usage": 1,
    "created_at": "2026-11-18T23:08:58.988Z",
    "expires_at": null,
    "test_mode": false
  },
  "instance": null,
  "meta": {
    "store_id": 79,
    "order_id": null,
    "order_item_id": 305,
    "product_id": 75,
    "product_name": "Inkwell",
    "variant_id": 75,
    "variant_name": "Default",
    "customer_id": 69,
    "customer_name": "Ada Lovelace",
    "customer_email": "ada@example.com"
  },
  "token": "sgt1.eyJ2IjoxLCJsaWQiOjMwNSwi…"
}

A known key always answers 200, whether or not it is valid. Read valid, not just the status code: expired and disabled licenses answer 200 with valid: false, an error to show, and a token whose own valid is false.

Expired license200 OK
{
  "valid": false,
  "error": "This license key has expired.",
  "license_key": { "id": 305, "status": "expired", "expires_at": "2026-10-01T00:00:00.000Z", … },
  "instance": null,
  "meta": { … },
  "token": "sgt1.eyJ2IjoxLCJsaWQiOjMwNSwi…"
}

Errors

StatuserrorCause
400license_key: Invalid input: expected string, received undefinedA parameter is missing or malformed.
404license_key not found.No such key.
404instance_id not found.The key exists, but that instance does not, or it was deactivated. The body includes license_key, instance: null and meta. Activate again.
429Too many requests. Try again in a minute.See rate limits.
503A generic messageTemporary failure on our side. Retry-After: 5.
Unknown key404 Not Found
{
  "valid": false,
  "error": "license_key not found."
}
Unknown instance404 Not Found
{
  "valid": false,
  "error": "instance_id not found.",
  "license_key": { "id": 305, "status": "active", … },
  "instance": null,
  "meta": { … }
}

POST /v1/licenses/deactivate

Frees one device so the customer can use the seat elsewhere.

Parameters

NameTypeDescription
license_keystring, requiredThe customer's key.
instance_idstring, requiredThe instance.id to remove.

Request

curl
curl https://clavem.io/v1/licenses/deactivate \
  -d license_key="YOUR-LICENSE-KEY" \
  -d instance_id="47596ad9-a811-4ebf-ac8a-03fc7b6d2a17"

Response

Response200 OK
{
  "deactivated": true,
  "error": null,
  "license_key": {
    "id": 305,
    "status": "active",
    "key": "S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8",
    "activation_limit": 3,
    "activation_usage": 1,
    "created_at": "2026-11-18T23:08:58.988Z",
    "expires_at": null,
    "test_mode": false
  },
  "meta": { … }
}

activation_usage in the response is the count after removal. When the last device goes, an active license returns to inactive. A removed instance id is gone for good: activate again to get a new one.

Errors

StatuserrorCause
400instance_id: Invalid input: expected string, received undefinedA parameter is missing or malformed.
404license_key not found.No such key.
404instance_id not found.No active instance with that id on this license. The body includes license_key and meta.
429Too many requests. Try again in a minute.See rate limits.
503A generic messageTemporary failure on our side. Retry-After: 5.
Unknown key404 Not Found
{
  "deactivated": false,
  "error": "license_key not found."
}

The license_key object

FieldTypeMeaning
idnumberThe license id. For an imported license, the id it had at Lemon Squeezy.
statusstringinactive, active, expired or disabled. See the status model.
keystringThe key as stored.
activation_limitnumber or nullHow many devices may be active at once. null means unlimited.
activation_usagenumberDevices active now.
created_atstringWhen the license was issued or imported.
expires_atstring or nullWhen it stops being valid. null for perpetual licenses.
test_modebooleantrue for licenses created by a Stripe test-mode purchase.

meta carries store_id, order_id, order_item_id, product_id, product_name,variant_id, variant_name, customer_id, customer_name and customer_email. For licenses imported from Lemon Squeezy the ids are the original ones, because Lemon Squeezy's documentation tells apps to check them. For the rest, they are Clavem's own ids, and order_id is null when the license was created by hand.

The status model

StatusvalidMeaning
inactivetrueIssued, with no device active. Never activated, or every device was removed.
activetrueAt least one device is active.
expiredfalseexpires_at has passed, or the Stripe subscription ended.
disabledfalseYou disabled it, or its order was fully refunded.

Precedence is disabled, then expired, then active or inactive. Expiry is evaluated when the license is read, so there is no delay between the date passing and the API saying so. An expired license comes back to life when a renewal is paid or you move expires_at forward. A disabled license stays disabled until you enable it, whatever Stripe says.

Errors

The License API keeps the flat shape apps already parse: the boolean for the call set to false and an error string. The management API and the releases endpoint use a structured shape instead, described under management errors. Do not parse error text for logic. Branch on the HTTP status and on valid.

Rate limits

  • License API: 120 requests per 60 seconds per IP address, and 60 requests per 60 seconds per license key. A request has to pass both.
  • Releases endpoint: 120 requests per 60 seconds per IP address, counted separately from the License API, so an update check does not use up your validation budget.
  • Management API: 300 requests per 60 seconds per API key.

Over the limit, the API answers 429 with Retry-After: 60. Plan limits are a different thing. They never affect the License API or the releases endpoint.

Over the limit429 Too Many Requests
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "valid": false,
  "error": "Too many requests. Try again in a minute."
}

CORS

The License API answers with Access-Control-Allow-Origin: * and allows POST and OPTIONS. Preflight responses are cacheable for 24 hours. This is deliberate: desktop apps, Electron renderers and browser extensions call it directly. The releases endpoint allows GET and OPTIONS, and the X-License-Key request header. Cookies are never used. The management API sends no CORS headers because it must only be called from a server.

Management API

For your own backend: create licenses, look them up, change limits and expiry, and disable them. To bring over keys you already sold, up to 500 per call with their devices, use POST /v1/admin/licenses/import.

Authentication

Create an API key under Developers in the dashboard. Send it as a bearer token. Keys start with sk_clavem_, are shown once, and can be revoked at any time. Keep them on your server.

Header
Authorization: Bearer sk_clavem_…

Base URL: https://clavem.io/v1/admin. Bodies and responses are JSON. Single objects and lists are wrapped in data.

Pagination

Lists are newest first. limit is 1 to 100 and defaults to 50. To get the next page, pass the next_before from the last response as before. When next_before is null, there are no more.

Errors

Every non-2xx response from the management API, the releases endpoint and the rest of the platform outside the License API has the same shape. Branch on code; message is for people.

Error shape401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": "This API key is not valid or has been revoked."
  }
}
StatuscodeMeaning
400bad_requestA parameter is missing or invalid. The message names it.
401unauthorizedNo bearer token, or the key is invalid or revoked.
402plan_limitCreating the license would pass the plan's active-license limit. See pricing.
404not_foundNo such object in your account.
429rate_limitedWith Retry-After: 60.
500internalOur fault. Details stay in our logs.

GET /v1/admin/products

Lists your products, newest first. Use it to find the id and the public_key for offline verification.

Response200 OK
{
  "data": [
    {
      "id": 75,
      "name": "Inkwell",
      "activation_limit": 3,
      "validity": "perpetual",
      "validity_days": null,
      "public_key": "kq1…your key…9fA",
      "archived": false,
      "created_at": "2026-11-18T23:08:58.201Z"
    }
  ]
}

activation_limit is the product's default device limit, null for unlimited. validity is perpetual, days or subscription.

GET /v1/admin/licenses

Lists licenses, newest first, optionally filtered.

QueryDescription
emailThe buyer's email address, exact match.
keyA license key, matched the way the License API matches it.
product_idOnly licenses of this product.
limit1 to 100. Default 50.
beforeA license id. Returns licenses older than it.
Response200 OK
{
  "data": [ { "id": 412, "key": "7QX2M-…", "status": "inactive", … } ],
  "next_before": 398
}

POST /v1/admin/licenses

Creates one license, an order for it and a private order page. The license starts inactive. If the email is new, a customer is created.

NameTypeDescription
product_idinteger, requiredOne of your products. Archived products are refused.
emailstring, requiredThe buyer's email address.
namestring, optionalThe buyer's name, up to 120 characters.
activation_limitinteger or null, optional1 to 10000, or -1 for unlimited. null or omitted uses the product's limit. 0 is refused.
expires_atISO 8601 date or null, optionalnull means never. Omitted follows the product's validity: perpetual, or a number of days from now.
Request
curl https://clavem.io/v1/admin/licenses \
  -H "Authorization: Bearer sk_clavem_…" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 75,
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "activation_limit": 2,
    "expires_at": "2027-11-19T00:00:00Z"
  }'
Response201 Created
{
  "data": {
    "id": 412,
    "key": "7QX2M-9WZ2P-H5RB8-K4TEV-0A1CD",
    "status": "inactive",
    "activation_limit": 2,
    "activation_usage": 0,
    "expires_at": "2027-11-19T00:00:00.000Z",
    "product_id": 75,
    "product_name": "Inkwell",
    "customer_email": "ada@example.com",
    "customer_name": "Ada Lovelace",
    "subscription_id": null,
    "test_mode": false,
    "created_at": "2026-11-19T09:20:03.114Z",
    "last_validated_at": null,
    "order_url": "https://clavem.io/o/412-…"
  }
}

order_url is the buyer's order page. Creating licenses by hand counts against your plan like any other, and past the limit it answers 402. Stripe purchases are never blocked.

Over the plan limit402 Payment Required
{
  "error": {
    "code": "plan_limit",
    "message": "The Free plan covers 50 active licenses and you have 50. Upgrade to Indie to add this one. Purchases through Stripe are never blocked."
  }
}

GET /v1/admin/licenses/:id

One license, with its order link and its active devices.

Response200 OK
{
  "data": {
    "id": 305,
    "key": "S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8",
    "status": "active",
    …
    "order_url": null,
    "instances": [
      {
        "id": "47596ad9-a811-4ebf-ac8a-03fc7b6d2a17",
        "name": "Ada's MacBook Pro",
        "created_at": "2026-11-18T23:08:58.990Z",
        "last_seen_at": "2026-11-19T07:41:12.508Z"
      }
    ]
  }
}

The license object has these fields: id, key, status, activation_limit, activation_usage, expires_at, product_id, product_name, customer_email, customer_name,subscription_id (the Stripe subscription, or null), test_mode, created_at andlast_validated_at. Here id is always Clavem's own id, also for imported licenses.

PATCH /v1/admin/licenses/:id

Changes the device limit, the expiry, or whether the license is disabled. Send any of these; omitted fields stay as they are.

NameTypeDescription
activation_limitinteger or nullAs when creating.
expires_atISO 8601 date or nullA new expiry. Moving it into the future, or to null, revives an expired license.
disabledbooleantrue disables the license. false enables it again, as active when a device is using it and inactive when not.
Disable a license
curl -X PATCH https://clavem.io/v1/admin/licenses/412 \
  -H "Authorization: Bearer sk_clavem_…" \
  -H "Content-Type: application/json" \
  -d '{ "disabled": true }'

The response is the updated license object, as under GET, without order_url and instances.

The management API does not create products or delete licenses. Disable instead, so the key keeps answering with a reason.

Releases endpoint

GET /v1/releases/:productId/latest

The newest published release of a product. Public, so an app can check for updates. A valid license key adds download links. The files, links and platform labels are explained in Releases and downloads.

NameWhereDescription
:productIdpathThe product's id, as in the products list and in the token's pid.
license_keyquery or X-License-Key headerOptional. With a license that is valid for this product, each file carries a url.
platformqueryOptional. Only files for this platform, plus files with no platform.
Request
curl "https://clavem.io/v1/releases/75/latest?platform=macos" \
  -H "X-License-Key: YOUR-LICENSE-KEY"
Response200 OK
{
  "version": "3.2.1",
  "notes": "Fixes a crash when importing large files.",
  "published_at": "2026-11-19T08:30:00.000Z",
  "files": [
    {
      "id": 12,
      "filename": "Inkwell-3.2.1.dmg",
      "size": 50540748,
      "platform": "macos",
      "url": "https://clavem.io/d/12?exp=1795050000&sig=…"
    }
  ]
}

url is signed and valid for one hour. It is absent without a valid key. A missing, unknown, revoked or foreign key is not an error: the response still tells your app that an update exists.

No release yet404 Not Found
{
  "error": {
    "code": "not_found",
    "message": "This product has no published release yet."
  }
}