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
POSTrequests 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,validordeactivated) with anerrorthat isnullor 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:
IandLread as1,Oas0,UasV. 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
| Name | Type | Description |
|---|---|---|
license_key | string, required | The customer's key. |
instance_name | string, required | A name for the device, up to 120 characters. Shown to the customer on the device page and to you in the dashboard. |
fingerprint | string, optional | A 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 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
{
"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
| Status | error | Cause |
|---|---|---|
| 400 | instance_name: Invalid input: expected string, received undefined | A parameter is missing or malformed. The message starts with the parameter name. |
| 400 | This license key has been disabled. | Status disabled. The body includes license_key and meta. |
| 400 | This license key has expired. | Status expired. The body includes license_key and meta. |
| 400 | This 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. |
| 404 | license_key not found. | No such key. |
| 429 | Too many requests. Try again in a minute. | See rate limits. |
| 503 | A generic message | Temporary failure on our side. Retry-After: 5. |
{
"activated": false,
"error": "This license key has reached the activation limit.",
"license_key": { "id": 305, "status": "active", "activation_limit": 3, "activation_usage": 3, … },
"meta": { … }
}{
"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
| Name | Type | Description |
|---|---|---|
license_key | string, required | The customer's key. |
instance_id | string, optional | The 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 https://clavem.io/v1/licenses/validate \
-d license_key="S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8" \
-d instance_id="47596ad9-a811-4ebf-ac8a-03fc7b6d2a17"Response
{
"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.
{
"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
| Status | error | Cause |
|---|---|---|
| 400 | license_key: Invalid input: expected string, received undefined | A parameter is missing or malformed. |
| 404 | license_key not found. | No such key. |
| 404 | instance_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. |
| 429 | Too many requests. Try again in a minute. | See rate limits. |
| 503 | A generic message | Temporary failure on our side. Retry-After: 5. |
{
"valid": false,
"error": "license_key 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
| Name | Type | Description |
|---|---|---|
license_key | string, required | The customer's key. |
instance_id | string, required | The instance.id to remove. |
Request
curl https://clavem.io/v1/licenses/deactivate \
-d license_key="YOUR-LICENSE-KEY" \
-d instance_id="47596ad9-a811-4ebf-ac8a-03fc7b6d2a17"Response
{
"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
| Status | error | Cause |
|---|---|---|
| 400 | instance_id: Invalid input: expected string, received undefined | A parameter is missing or malformed. |
| 404 | license_key not found. | No such key. |
| 404 | instance_id not found. | No active instance with that id on this license. The body includes license_key and meta. |
| 429 | Too many requests. Try again in a minute. | See rate limits. |
| 503 | A generic message | Temporary failure on our side. Retry-After: 5. |
{
"deactivated": false,
"error": "license_key not found."
}The license_key object
| Field | Type | Meaning |
|---|---|---|
id | number | The license id. For an imported license, the id it had at Lemon Squeezy. |
status | string | inactive, active, expired or disabled. See the status model. |
key | string | The key as stored. |
activation_limit | number or null | How many devices may be active at once. null means unlimited. |
activation_usage | number | Devices active now. |
created_at | string | When the license was issued or imported. |
expires_at | string or null | When it stops being valid. null for perpetual licenses. |
test_mode | boolean | true 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
| Status | valid | Meaning |
|---|---|---|
| inactive | true | Issued, with no device active. Never activated, or every device was removed. |
| active | true | At least one device is active. |
| expired | false | expires_at has passed, or the Stripe subscription ended. |
| disabled | false | You 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.
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.
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": {
"code": "unauthorized",
"message": "This API key is not valid or has been revoked."
}
}| Status | code | Meaning |
|---|---|---|
| 400 | bad_request | A parameter is missing or invalid. The message names it. |
| 401 | unauthorized | No bearer token, or the key is invalid or revoked. |
| 402 | plan_limit | Creating the license would pass the plan's active-license limit. See pricing. |
| 404 | not_found | No such object in your account. |
| 429 | rate_limited | With Retry-After: 60. |
| 500 | internal | Our 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.
{
"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.
| Query | Description |
|---|---|
email | The buyer's email address, exact match. |
key | A license key, matched the way the License API matches it. |
product_id | Only licenses of this product. |
limit | 1 to 100. Default 50. |
before | A license id. Returns licenses older than it. |
{
"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.
| Name | Type | Description |
|---|---|---|
product_id | integer, required | One of your products. Archived products are refused. |
email | string, required | The buyer's email address. |
name | string, optional | The buyer's name, up to 120 characters. |
activation_limit | integer or null, optional | 1 to 10000, or -1 for unlimited. null or omitted uses the product's limit. 0 is refused. |
expires_at | ISO 8601 date or null, optional | null means never. Omitted follows the product's validity: perpetual, or a number of days from now. |
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"
}'{
"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.
{
"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.
{
"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.
| Name | Type | Description |
|---|---|---|
activation_limit | integer or null | As when creating. |
expires_at | ISO 8601 date or null | A new expiry. Moving it into the future, or to null, revives an expired license. |
disabled | boolean | true disables the license. false enables it again, as active when a device is using it and inactive when not. |
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.
| Name | Where | Description |
|---|---|---|
:productId | path | The product's id, as in the products list and in the token's pid. |
license_key | query or X-License-Key header | Optional. With a license that is valid for this product, each file carries a url. |
platform | query | Optional. Only files for this platform, plus files with no platform. |
curl "https://clavem.io/v1/releases/75/latest?platform=macos" \
-H "X-License-Key: YOUR-LICENSE-KEY"{
"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.
{
"error": {
"code": "not_found",
"message": "This product has no published release yet."
}
}