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 :
- Le logiciel envoie la clé de licence et un identifiant de l’appareil à ton serveur.
- Ton serveur appelle
POST /v1/license-keys/validateouactivateavec ta clé API. - 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:readetlicense_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.
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 :
{
"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
isActivevauttrue. Sinon,statusdit pourquoi, pour que tu l’expliques à ton utilisateur. - Une clé inconnue, ou d’une autre boutique, reçoit
404 license_key_not_found.
status | Ce que ça veut dire |
|---|---|
active | Payée, ni expirée ni révoquée. |
pending | Payé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. |
expired | Sa date d’expiration est passée. Racheter la licence donne une nouvelle clé. |
revoked | Ré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 :
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" }'deviceIdentifierest 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
200sans prendre de nouvelle place : tu peux appeleractivateà 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 :
| Statut | code | Quand |
|---|---|---|
| 404 | license_key_not_found | Clé inconnue, ou d’une autre boutique. |
| 409 | activation_limit_reached | Tous les appareils de la clé sont pris. |
| 409 | license_key_expired | La clé a expiré. |
| 409 | license_key_revoked | La clé est révoquée. |
| 409 | license_key_pending | La clé attend encore une clé du stock. |
| 400 | validation_failed | deviceIdentifier absent, vide ou trop long. |
Libérer un appareil
Quand ton utilisateur change d’ordinateur, libère l’ancien :
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
validatejusqu’à 24 heures sur ton serveur, et laisse le logiciel s’ouvrir hors ligne pendant ce temps. - Écoute le webhook
license_key.revokedpour 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}.
| Type | Quand | En plus dans data |
|---|---|---|
license_key.issued | Une clé est donnée à l’acheteur. | — |
license_key.activated | Un appareil est activé. | activation: { deviceIdentifier, at } |
license_key.deactivated | Un appareil est libéré. | activation: { deviceIdentifier, at } |
license_key.revoked | Une clé est révoquée, par toi ou par un remboursement. | reason : refund, ton texte ou null |
license_key.expiring | Une clé expire dans sept jours au plus (vérifié chaque jour à 06:00 UTC). | daysUntilExpiry |
license_key.expired | Une 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
| Route | Portée | Ce qu’elle fait |
|---|---|---|
GET /v1/license-keys | license_keys:read | Les clés de la boutique, filtrées par productId, status, email ou externalReference. |
GET /v1/license-keys/{id} | license_keys:read | Une clé, avec sa valeur complète. |
GET /v1/license-keys/{id}/activations | license_keys:read | L’historique des appareils de la clé, désactivés compris. |
POST /v1/license-keys/{id}/revoke | license_keys:write | Ré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.