Vérifier une clé de licence

Ton logiciel demande à ton serveur si la clé de son utilisateur est valable, et ton serveur le demande à Kivoo.

Quand tu vends une licence sur Kivoo, chaque commande payée donne à l’acheteur une clé de licence, par exemple BAU-XKCD-92HF-LM7P-Q4RT. L’acheteur la colle dans ton logiciel, et ton logiciel vérifie qu’elle est valable avant de s’ouvrir. Ce guide montre comment.

Tu édites un SaaS, où l’utilisateur a déjà un compte ? Il n’a pas besoin de clé : lis plutôt Encaisser depuis ton application.

Le principe

Ton logiciel ne parle pas à Kivoo. Il parle à ton serveur, qui parle à Kivoo avec ta clé API :

  1. Le logiciel envoie la clé de licence et un identifiant de l’appareil à ton serveur.
  2. Ton serveur appelle POST /v1/license-keys/validate ou activate avec ta clé API.
  3. Ton serveur répond au logiciel : ouvert ou fermé, et pourquoi.

Ne mets jamais ta clé API dans ton logiciel

Une clé API livrée dans un logiciel installé se lit en quelques minutes, et elle donne accès à toutes les clés de licence de ta boutique. Elle reste sur ton serveur.

Ce qu’il te faut

  • Une licence publiée. Dans le dashboard, Produits › Créer un produit › Licence. L’étape Clés fixe le mode de distribution (clés automatiques ou stock de clés), la durée de validité (en jours, ou aucune pour une clé permanente), le nombre d’appareils et les instructions d’activation, que l’acheteur reçoit avec sa clé.
  • Une clé API avec la portée Clés de licence en lecture et écriture (license_keys:read et license_keys:write) : voir Authentification.

Vérifier une clé

Au démarrage du logiciel, ton serveur envoie la clé dans le corps de la requête, jamais dans l’adresse : une adresse finit dans les journaux des proxys.

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 répond 200 avec la clé, quel que soit son état :

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
}
  • Ouvre le logiciel si isActive vaut true. Sinon, status dit pourquoi, pour que tu l’expliques à ton utilisateur.
  • Une clé inconnue, ou d’une autre boutique, reçoit 404 license_key_not_found.
statusCe que ça veut dire
activePayée, ni expirée ni révoquée.
pendingPayée, mais le stock de clés était vide : la clé part d’elle-même dès que tu en ajoutes. Seulement en mode stock de clés.
expiredSa date d’expiration est passée. Racheter la licence donne une nouvelle clé.
revokedRévoquée par toi, ou parce que la commande a été remboursée. C’est définitif.

La validité court dès le paiement, pas dès la première activation. La durée et le nombre d’appareils sont ceux de la licence au moment de la vente : les changer ensuite ne touche que les ventes suivantes.

Activer un appareil

Chaque clé admet un nombre d’appareils. Quand le logiciel s’installe sur un appareil, ton serveur le déclare :

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 est obligatoire, 255 caractères au plus. Choisis une valeur stable pour un appareil et qui ne dit rien de son propriétaire : une empreinte de l’identifiant matériel, par exemple, plutôt que le nom de l’ordinateur.
  • Le même appareil activé deux fois reçoit 200 sans prendre de nouvelle place : tu peux appeler activate à chaque démarrage.
  • Kivoo garde l’adresse IP et le navigateur (User-Agent) de l’appel, que tu retrouves dans l’historique de la clé.

Les refus :

StatutcodeQuand
404license_key_not_foundClé inconnue, ou d’une autre boutique.
409activation_limit_reachedTous les appareils de la clé sont pris.
409license_key_expiredLa clé a expiré.
409license_key_revokedLa clé est révoquée.
409license_key_pendingLa clé attend encore une clé du stock.
400validation_faileddeviceIdentifier absent, vide ou trop long.

Libérer un appareil

Quand ton utilisateur change d’ordinateur, libère l’ancien :

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" }'

Un appareil qui n’est pas activé reçoit 404 activation_not_found. L’activation désactivée reste dans l’historique de la clé. Tu peux aussi libérer un appareil depuis le dashboard, sur la page Clés du produit.

Garder la réponse en cache

Ne fais pas dépendre chaque démarrage du logiciel d’un appel à Kivoo :

  • Garde la réponse de validate jusqu’à 24 heures sur ton serveur, et laisse le logiciel s’ouvrir hors ligne pendant ce temps.
  • Écoute le webhook license_key.revoked pour couper l’accès tout de suite quand une clé est révoquée ou remboursée, sans attendre la fin du cache.

validate, activate et deactivate ont droit à 600 requêtes par minute et par clé API, pour absorber les démarrages du matin. Les autres routes gardent la limite commune de 120.

Boutique suspendue

Si ta boutique est suspendue, ses clés API sont refusées (403 store_unavailable), donc plus aucune vérification ne passe. Prévois ce cas dans ton logiciel, par exemple en gardant la dernière réponse connue.

Réagir aux webhooks

Abonne un webhook aux événements des clés. data est la clé, comme dans la liste de l’API : elle porte keyHint mais jamais la clé complète, que Kivoo n’écrit dans aucun webhook. Pour la lire, appelle GET /v1/license-keys/{id}.

TypeQuandEn plus dans data
license_key.issuedUne clé est donnée à l’acheteur.—
license_key.activatedUn appareil est activé.activation: { deviceIdentifier, at }
license_key.deactivatedUn appareil est libéré.activation: { deviceIdentifier, at }
license_key.revokedUne clé est révoquée, par toi ou par un remboursement.reason : refund, ton texte ou null
license_key.expiringUne clé expire dans sept jours au plus (vérifié chaque jour à 06:00 UTC).daysUntilExpiry
license_key.expiredUne clé vient d’expirer (vérifié toutes les heures).—

L’acheteur reçoit aussi, avec license_key.expiring, un e-mail « Ta clé de licence expire bientôt » qui l’invite à racheter la licence. Chaque avis part une seule fois par clé, et jamais pour une clé permanente ou révoquée.

Lister et révoquer

RoutePortéeCe qu’elle fait
GET /v1/license-keyslicense_keys:readLes clés de la boutique, filtrées par productId, status, email ou externalReference.
GET /v1/license-keys/{id}license_keys:readUne clé, avec sa valeur complète.
GET /v1/license-keys/{id}/activationslicense_keys:readL’historique des appareils de la clé, désactivés compris.
POST /v1/license-keys/{id}/revokelicense_keys:writeRévoque la clé, définitivement, avec un reason facultatif (500 caractères au plus).

La liste ne donne que keyHint, jamais la valeur complète. Elle suit les conventions de pagination.

Chaque route est décrite en détail, avec ses paramètres et ses réponses, dans la section Clés de licence de la référence.

Sur cette page