Guides

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:

  1. The software sends the license key and a device identifier to your server.
  2. Your server calls POST /v1/license-keys/validate or activate with your API key.
  3. 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:read and license_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.

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

200 OK
{
  "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 isActive is true. Otherwise status says why, so you can tell your user.
  • An unknown key, or one of another store, gets 404 license_key_not_found.
statusWhat it means
activePaid, neither expired nor revoked.
pendingPaid, but the key stock was empty: the key goes out on its own as soon as you add keys. Key stock mode only.
expiredIts expiry date has passed. Buying the license again gives a new key.
revokedRevoked 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:

Terminal
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" }'
  • deviceIdentifier is 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 200 without taking a new place: you may call activate on every start.
  • Kivoo keeps the IP address and the User-Agent of the call, which you find in the key’s history.

Refusals:

StatuscodeWhen
404license_key_not_foundUnknown key, or one of another store.
409activation_limit_reachedEvery device of the key is taken.
409license_key_expiredThe key has expired.
409license_key_revokedThe key is revoked.
409license_key_pendingThe key is still waiting for a key from the stock.
400validation_faileddeviceIdentifier missing, empty or too long.

Free a device

When your user changes computer, free the old one:

Terminal
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 validate for up to 24 hours on your server, and let the software open offline in the meantime.
  • Listen to the license_key.revoked webhook 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}.

TypeWhenAlso in data
license_key.issuedA key is given to the buyer.—
license_key.activatedA device is activated.activation: { deviceIdentifier, at }
license_key.deactivatedA device is freed.activation: { deviceIdentifier, at }
license_key.revokedA key is revoked, by you or by a refund.reason: refund, your text or null
license_key.expiringA key expires in seven days or less (checked daily at 06:00 UTC).daysUntilExpiry
license_key.expiredA 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

RouteScopeWhat it does
GET /v1/license-keyslicense_keys:readThe store’s keys, filtered by productId, status, email or externalReference.
GET /v1/license-keys/{id}license_keys:readOne key, with its full value.
GET /v1/license-keys/{id}/activationslicense_keys:readThe key’s device history, deactivated ones included.
POST /v1/license-keys/{id}/revokelicense_keys:writeRevokes 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.

On this page