Check a license key
Your software asks your server whether its user’s key is valid, and your server asks Kivoo.
When you sell a license on Kivoo, each paid order gives the buyer a license key, for example BAU-XKCD-92HF-LM7P-Q4RT. The buyer pastes it into your software, and your software checks that it is valid before it opens. This guide shows how.
You run a SaaS, where the user already has an account? They need no key: read Accept payments from your app instead.
How it works
Your software does not talk to Kivoo. It talks to your server, which talks to Kivoo with your API key:
- The software sends the license key and a device identifier to your server.
- Your server calls
POST /v1/license-keys/validateoractivatewith your API key. - Your server answers the software: open or closed, and why.
Never put your API key in your software
An API key shipped in installed software is read within minutes, and it gives access to every license key of your store. It stays on your server.
What you need
- A published license. In the dashboard, Products › Create a product › License. The Keys step sets the distribution mode (automatic keys or key stock), the validity (in days, or none for a permanent key), the number of devices and the activation instructions the buyer receives with their key.
- An API key with the License keys scope in read and write (
license_keys:readandlicense_keys:write): see Authentication.
Check a key
When the software starts, your server sends the key in the request body, never in the URL: a URL ends up in proxy logs.
curl https://api.kivoo.africa/v1/license-keys/validate \
-H "Authorization: Bearer $KIVOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "key": "BAU-XKCD-92HF-LM7P-Q4RT" }'Kivoo answers 200 with the key, whatever its state:
{
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"key": "BAU-XKCD-92HF-LM7P-Q4RT",
"keyHint": "BAU-…-Q4RT",
"status": "active",
"isActive": true,
"issuedAt": "2026-10-15T09:12:00.000Z",
"expiresAt": "2026-11-14T09:12:00.000Z",
"revokedAt": null,
"activations": { "count": 1, "max": 1, "remaining": 0 },
"product": { "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b", "title": "Bauhaus Pro" },
"customer": { "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "email": "awa@example.com" },
"order": { "id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a", "reference": "KV-7F3K9QA2" },
"checkout": null
}- Open the software when
isActiveistrue. Otherwisestatussays why, so you can tell your user. - An unknown key, or one of another store, gets
404 license_key_not_found.
status | What it means |
|---|---|
active | Paid, neither expired nor revoked. |
pending | Paid, but the key stock was empty: the key goes out on its own as soon as you add keys. Key stock mode only. |
expired | Its expiry date has passed. Buying the license again gives a new key. |
revoked | Revoked by you, or because the order was refunded. It is final. |
Validity runs from the payment, not from the first activation. The validity and the number of devices are the license’s at the time of the sale: changing them later only affects later sales.
Activate a device
Each key admits a number of devices. When the software is installed on a device, your server declares it:
curl https://api.kivoo.africa/v1/license-keys/activate \
-H "Authorization: Bearer $KIVOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "key": "BAU-XKCD-92HF-LM7P-Q4RT", "deviceIdentifier": "mac-7f3a9c" }'deviceIdentifieris required, 255 characters at most. Pick a value that is stable for a device and says nothing about its owner: a hash of the hardware identifier, for example, rather than the computer’s name.- The same device activated twice gets
200without taking a new place: you may callactivateon every start. - Kivoo keeps the IP address and the
User-Agentof the call, which you find in the key’s history.
Refusals:
| Status | code | When |
|---|---|---|
| 404 | license_key_not_found | Unknown key, or one of another store. |
| 409 | activation_limit_reached | Every device of the key is taken. |
| 409 | license_key_expired | The key has expired. |
| 409 | license_key_revoked | The key is revoked. |
| 409 | license_key_pending | The key is still waiting for a key from the stock. |
| 400 | validation_failed | deviceIdentifier missing, empty or too long. |
Free a device
When your user changes computer, free the old one:
curl https://api.kivoo.africa/v1/license-keys/deactivate \
-H "Authorization: Bearer $KIVOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "key": "BAU-XKCD-92HF-LM7P-Q4RT", "deviceIdentifier": "mac-7f3a9c" }'A device that is not active gets 404 activation_not_found. The deactivated activation stays in the key’s history. You can also free a device from the dashboard, on the product’s Keys page.
Cache the answer
Do not make every start of the software depend on a call to Kivoo:
- Keep the answer of
validatefor up to 24 hours on your server, and let the software open offline in the meantime. - Listen to the
license_key.revokedwebhook to cut access at once when a key is revoked or refunded, without waiting for the cache to end.
validate, activate and deactivate get 600 requests a minute per API key, to absorb the morning starts. The other routes keep the common limit of 120.
Suspended store
If your store is suspended, its API keys are refused (403 store_unavailable), so no check goes
through any more. Plan for it in your software, for example by keeping the last known answer.
React to webhooks
Subscribe a webhook to the key events. data is the key, as in the API’s list: it holds keyHint but never the full key, which Kivoo writes in no webhook. To read it, call GET /v1/license-keys/{id}.
| Type | When | Also in data |
|---|---|---|
license_key.issued | A key is given to the buyer. | — |
license_key.activated | A device is activated. | activation: { deviceIdentifier, at } |
license_key.deactivated | A device is freed. | activation: { deviceIdentifier, at } |
license_key.revoked | A key is revoked, by you or by a refund. | reason: refund, your text or null |
license_key.expiring | A key expires in seven days or less (checked daily at 06:00 UTC). | daysUntilExpiry |
license_key.expired | A key has just expired (checked every hour). | — |
Along with license_key.expiring, the buyer also gets an e-mail, “Ta clé de licence expire bientôt” (your license key expires soon), inviting them to buy the license again. Each notice goes out once per key, and never for a permanent or revoked key.
List and revoke
| Route | Scope | What it does |
|---|---|---|
GET /v1/license-keys | license_keys:read | The store’s keys, filtered by productId, status, email or externalReference. |
GET /v1/license-keys/{id} | license_keys:read | One key, with its full value. |
GET /v1/license-keys/{id}/activations | license_keys:read | The key’s device history, deactivated ones included. |
POST /v1/license-keys/{id}/revoke | license_keys:write | Revokes the key, for good, with an optional reason (500 characters at most). |
The list holds keyHint only, never the full value. It follows the pagination conventions.
Each route is described in full, with its parameters and answers, in the License keys section of the reference.