Premiers pas

Voici le parcours de bout en bout pour un éditeur qui ajoute des licences à une application : obtenir un service d’émission, créer un produit et une clé de signature, embarquer le SDK dans votre produit, émettre une licence, la vérifier dans l’application et passer en production. Il se déroule de la même façon quel que soit le langage dans lequel vous livrez — l’étape 3 renvoie au SDK de votre langage (ou au parcours HTTP brut).

Keyright existe en deux modes de déploiement, et chaque étape ci-dessous présente les deux. Tout au long de la page, $BASE est l’URL de votre service d’émission et $TOKEN est votre identifiant d’administration, envoyé dans l’en-tête X-Admin-Token.

Choisissez votre parcours

Keyright Cloud — nous hébergeons le service d’émission ; vous vous inscrivez et commencez à émettre des clés. Auto-hébergé — vous déployez le service dans votre propre infrastructure. La partie que vous construisez est la même dans les deux cas : le code du SDK, le format signé des licences et la clé publique que vous livrez sont identiques. Seuls l’URL du service vers laquelle pointe votre application et l’identifiant d’administration avec lequel vous gérez l’espace de travail diffèrent.

1. Obtenez votre service d’émission

Cloud : créez un espace de travail sur keyright.delta1labs.com et connectez-vous. Votre espace de travail est provisionné automatiquement avec une clé de signature, vous pouvez donc passer directement à l’étape 2. Définissez $BASE=https://keyright.delta1labs.com ; votre $TOKEN est un jeton de session d’équipe — émis à la connexion, et vous pouvez inviter des coéquipiers (avec leurs propres jetons) sous Settings → Team.

Auto-hébergé : récupérez l’image de conteneur publique, pointez-la vers une base de données PostgreSQL vide, donnez-lui les secrets dont elle a besoin (un jeton d’administration, un secret de chiffrement des clés) et votre clé de licence Keyright, puis démarrez-la — elle construit son propre schéma au premier démarrage et répond sur /health quand elle est prête. Définissez $BASE sur l’URL de votre instance (en local, c’est http://localhost:8080) et $TOKEN sur le KEYRIGHT_ADMIN_TOKEN que vous avez généré. Le parcours complet est le guide de déploiement, et votre instance a besoin d’une clé valide pour fonctionner — voir Licence et éditions.

Tout ce qui suit est identique pour les deux modes ; seuls $BASE et $TOKEN changent.

Une fois connecté, vous arrivez sur l’accueil du tableau de bord, qui suit votre progression à travers exactement les étapes ci-dessous :

2. Créez un produit (et une édition), puis obtenez une clé de signature

Créez d’abord le produit — vous ne pouvez pas générer une clé de signature ni émettre une licence pour un produit qui n’existe pas. Depuis le tableau de bord (Products → New product, puis Editions → Add edition — le tableau de bord appelle les niveaux des éditions ; l’API dit toujours tiers), ou via l’API :

# créer le produit
curl -X POST $BASE/admin/products -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"name":"Acme App","slug":"acme-app"}'

# ajouter un niveau/une édition (nombre de sièges + un modèle de droits que votre application lit à l'exécution)
curl -X POST $BASE/admin/products/acme-app/tiers -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"name":"pro","seats":3,"entitlements":{"export":"true","max-projects":"10"}}'

Les valeurs de droits sont des chaînes sur le réseau ("true"/"false" pour les indicateurs, un entier ou "unlimited" pour les limites). Les quotas (licences actives, nombre de produits) suivent le plan du tenant sur Cloud ; les éditions payantes auto-hébergées sont illimitées. Si vous vendez des mises à jour (un an de mises à jour, une version majeure, un abonnement…), donnez à l’édition une politique de couverture avant d’émettre — voir Couverture des versions.

L’onglet Overview du produit rassemble tout cela — les éditions avec leurs nombres de sièges et leurs droits, l’essai et la clé de signature que vous embarquerez à l’étape suivante :

Obtenez une clé de signature. Les licences et les leases sont signées avec une clé RSA dont la moitié privée reste côté serveur ; votre application n’embarque que la clé publique. Une clé est soit par produit, soit à l’échelle du tenant (partagée par tous vos produits).

• Par produit (recommandé) : curl -X POST $BASE/admin/products/acme-app/signing-key -H "X-Admin-Token: $TOKEN" — la réponse inclut la signingPublicKey du produit. Dans le tableau de bord, elle se trouve sur l’onglet Signing key du produit.
• À l’échelle du tenant : lisez-la depuis Developers → Keys, ou GET $BASE/admin/public-key (également GET $BASE/admin/account → integration.signingPublicKey).

GET /admin/public-key et GET /admin/account renvoient la clé du tenant, qui vaut null tant qu’aucune clé de tenant n’existe. Sur une instance auto-hébergée toute neuve sans clé de tenant définie, générez une clé par produit (ci-dessus) plutôt que d’embarquer une valeur nulle. Un espace de travail Cloud possède déjà une clé de tenant.

Copiez la clé publique en base64 de la clé qui signe les licences de ce produit, quelle qu’elle soit — vous la collerez dans le SDK à l’étape 3. Le tableau de bord s’ouvre dans une vue Basique épurée qui couvre exactement ces étapes ; passez à la vue Intermédiaire ou Avancé quand vous avez besoin de tout le reste.

3. Mettez le SDK dans votre produit

C’est le cœur de l’intégration : embarquer le SDK, l’initialiser avec le slug de votre produit et la clé publique, et verrouiller une fonctionnalité. Le code est identique sur Cloud et en auto-hébergé — la seule chose qui change entre les modes est ServiceUrl (votre $BASE) et, côté serveur, le jeton d’administration qui a émis la clé. Le format de licence et la clé publique embarquée ne changent pas.

Le tableau de bord écrit pour vous la première version de ce code : Developers → Quickstart sélectionne votre produit et votre langage et préremplit l’extrait avec le slug du produit, sa clé publique et l’URL de cette instance — copiez-le tel quel.

Voici cette intégration minimale — installer, initialiser avec le slug du produit + la clé publique + l’URL du service, activer en ligne, puis verrouiller une fonctionnalité — dans chaque langage pris en charge. Définissez l’URL du service sur votre $BASE (l’URL hébergée sur Cloud, l’URL de votre instance en auto-hébergé) ; tout le reste — les appels du SDK, le format signé des licences/leases, la clé publique embarquée — est identique sur Cloud et en auto-hébergé.

.NET — Keyright.NET sur NuGet (multi-cible netstandard2.0 et net8.0, il fonctionne donc sur .NET Framework 4.8 et .NET 6–10) :

dotnet add package Keyright.NET

using Keyright.Client;

static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions
{
    Product         = "acme-app",                        // le slug du produit de l'étape 2
    PublicKeyBase64 = "MIIBIjANBgkq...",                 // la clé publique de l'étape 2 — pas un secret ; elle ne fait que vérifier
    ServiceUrl      = "https://keyright.delta1labs.com", // Cloud : l'URL hébergée. Auto-hébergé : l'URL de votre instance. Omettez pour le hors ligne uniquement.
});

// Quand le client saisit une clé, activez en ligne : lie cette machine, consomme un siège, met en cache une lease signée.
LicenseInfo info = await License.ActivateAsync(customerEnteredKey, ct);

// Chaque lancement ultérieur vérifie hors ligne avec la lease en cache — aucun aller-retour réseau.
LicenseInfo offline = License.Validate();

// Verrouillez une fonctionnalité payante sur un droit (pas sur l'édition), pour qu'un changement de niveau n'exige aucun nouveau code.
if (info.IsPaid && License.IsEnabled("export"))
    ShowExportCommand();

Node.js — keyright sur npm (CommonJS, zéro dépendance) :

npm install keyright

const { KeyrightClient } = require('keyright');

const license = KeyrightClient.initialize({
  product:         'acme-app',                          // le slug du produit de l'étape 2
  publicKeyBase64: 'MIIBIjANBgkq...',                   // la clé publique de l'étape 2 — pas un secret
  serviceUrl:      'https://keyright.delta1labs.com',   // Cloud : l'URL hébergée. Auto-hébergé : l'URL de votre instance.
});

// Quand le client saisit une clé, activez en ligne (lie la machine, consomme un siège, met en cache une lease signée).
const info = await license.activate(customerEnteredKey);

// Les lancements ultérieurs vérifient hors ligne avec la lease en cache — synchrone, ne lève jamais d'exception.
const { info: offline } = license.validate();

// Verrouillez une fonctionnalité payante sur un droit.
if (info.isPaid && info.entitlements.isEnabled('export')) {
  showExportCommand();
}

Python — keyright sur PyPI (Python 3.8+) :

pip install "keyright>=1.1.4"

from keyright import KeyrightClient, KeyrightOptions

license = KeyrightClient.initialize(KeyrightOptions(
    product="acme-app",                              # le slug du produit de l'étape 2
    public_key_base64="MIIBIjANBgkq...",             # la clé publique de l'étape 2 — pas un secret
    service_url="https://keyright.delta1labs.com",   # Cloud : l'URL hébergée. Auto-hébergé : l'URL de votre instance.
))

# Quand le client saisit une clé, activez en ligne (synchrone).
info = license.activate(customer_entered_key)

# Les lancements ultérieurs vérifient hors ligne avec la lease en cache ; validate() renvoie (info, source).
offline, source = license.validate()

# Verrouillez une fonctionnalité payante sur un droit.
if info.is_paid and info.entitlements.is_enabled("export"):
    show_export_command()

Java — com.delta1labs:keyright sur Maven Central (Java 17+, aucune dépendance à l’exécution) :

<dependency>
  <groupId>com.delta1labs</groupId>
  <artifactId>keyright</artifactId>
  <version>1.1.4</version>
</dependency>

import com.delta1labs.keyright.KeyrightClient;
import com.delta1labs.keyright.KeyrightOptions;
import com.delta1labs.keyright.LicenseInfo;

KeyrightClient client = KeyrightClient.initialize(
    new KeyrightOptions()
        .product("acme-app")                                 // le slug du produit de l'étape 2
        .publicKeyBase64("MIIBIjANBgkq...")                  // la clé publique de l'étape 2 — pas un secret
        .serviceUrl("https://keyright.delta1labs.com"));     // Cloud : l'URL hébergée. Auto-hébergé : l'URL de votre instance.

// Quand le client saisit une clé, activez en ligne (synchrone).
LicenseInfo info = client.activate(customerEnteredKey);

// Les lancements ultérieurs vérifient hors ligne avec la lease en cache.
LicenseInfo offline = client.validateInfo();

// Verrouillez une fonctionnalité payante sur un droit.
if (info.isPaid() && info.entitlements.isEnabled("export")) {
    showExportCommand();
}

Tout langage (HTTP brut, sans SDK) — l’API runtime est du simple JSON sur HTTP, donc Go, Rust, C++, PHP, Ruby… lui parlent directement. Activez une machine, puis vérifiez vous-même la lease signée :

curl -s -X POST "$BASE/v1/activate" -H "content-type: application/json" \
  -d '{"key":"LIC-9F3A...","machineId":"<your stable per-machine id>","product":"acme-app"}'
# -> { "status":"ok", "seats":3, "used":1, "lease":"{...signed lease JSON...}" }

Stockez la chaîne lease telle quelle et vérifiez sa signature RSA avec votre clé publique embarquée — reconstruisez la charge utile canonique krlease1|… et contrôlez-la avec PKCS#1 v1.5 / SHA-256 — avant de lui faire confiance. Une fois vérifiée, lisez tier pour l’édition et entitlements pour les verrous par fonctionnalité, et revalidez périodiquement (POST /v1/validate) pour prendre en compte les révocations. Échouez en mode fermé sur tout statut autre que ok ou sur une lease qui ne se vérifie pas. La recette complète au niveau des octets (avec un exemple Go que vous pouvez porter) se trouve dans Utiliser l’API HTTP directement.

Chaque SDK vérifie la signature avec votre clé publique embarquée, contrôle la liaison à la machine et l’expiration, met la lease en cache localement et se réactive automatiquement avant son expiration. Tous échouent en mode fermé vers l’état gratuit/sans licence si la vérification échoue ou si la clé est révoquée — et comme les cinq clients vérifient le même format signé, une gamme de produits multi-langages partage un seul tenant et une seule clé publique.

Pour le parcours complet par langage — désactivation, leases hors ligne/isolées (air-gapped), essais, verrouillage par machine, rotation des clés et couverture des versions — suivez le guide complet du vôtre :

Langage	Paquet	Guide
.NET	Keyright.NET (NuGet)	Intégration du SDK .NET
Node.js	keyright (npm)	Intégration du SDK Node.js
Python	keyright (PyPI)	Intégration du SDK Python
Java	com.delta1labs:keyright (Maven)	Intégration du SDK Java
Tout autre langage (Go, Rust, C++, PHP…)	—	Utiliser l’API HTTP directement

Qu’est-ce qui diffère entre Cloud et auto-hébergé ? Seulement l’URL de base et le jeton d’administration. Définissez ServiceUrl sur l’URL hébergée pour Cloud ou sur l’URL de votre instance en auto-hébergé ; tout le reste — les appels du SDK, le format des licences et des leases, l’embarquement de la clé publique — est identique. Voir Verrouillage de fonctionnalités pour les droits et les limites en profondeur.

4. Émettez une licence et vérifiez-la dans l’application

Émettez une licence payante depuis Licenses → Issue license dans le tableau de bord, ou via l’API (omettez id pour générer automatiquement la clé ; incluez-le pour importer une clé existante) :

curl -X POST $BASE/admin/licenses -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"licensee":"Acme Inc.","product":"acme-app","tier":"pro","seats":3,"email":"owner@acme.com"}'
# -> HTTP 201
# { "id":"LIC-XXXX...", "licensee":"Acme Inc.", "product":"acme-app", "tier":"pro",
#   "seats":3, "used":0, "expiryUtc":null, "revoked":false, "trial":false, "createdAt":"..." }
# L'"id" est la clé que vous remettez au client.

Le client colle cette clé dans votre application, qui appelle ActivateAsync (en ligne) — cela lie la machine, consomme un siège et met en cache une lease signée pour que les appels Validate() ultérieurs réussissent hors ligne. La liaison à la machine est automatique : Activate ne prend que la clé ; le SDK dérive un identifiant de machine stable à partir de l’hôte, de sorte qu’une clé mono-poste ne peut pas tourner sur deux machines (le corps HTTP brut de POST /v1/activate porte { key, machineId, product } — le SDK renseigne machineId pour vous). Ce que vous lisez dans LicenseInfo :

• IsPaid / IsTrial — s’il s’agit d’une licence payante ou d’essai (les deux s’activent par le même chemin).
• IsEnabled("flag") / GetLimit("name", fallback) — des vérifications de droits qui échouent en mode fermé.
• DaysRemaining / ExpiryUtc — pour un badge « 27 jours restants » ; StatusBadge pour un libellé comme « Pro Trial ».

À mesure que chaque machine s’active, elle apparaît sur l’onglet Devices de cette licence, consommant un siège — vous pouvez voir quels appareils sont liés, libérer un siège et lire les droits que porte la licence :

Les chemins complets d’activation et hors ligne se trouvent dans Activation et sièges et Hors ligne et isolé (air-gapped).

Obtenir une clé d’essai. Si vous avez activé un essai en libre-service sur le produit (Products → Trials), votre application obtient une clé d’essai en appelant directement l’endpoint public d’essai — il n’y a pas d’enveloppe SDK pour émettre un essai :

curl -X POST $BASE/v1/trial -H "content-type: application/json" \
  -d '{"product":"acme-app","email":"user@customer.com","company":"Customer Ltd"}'
# -> { "ok":true, "product":"acme-app", "trial":true, "emailed":true, "expiresUtc":"...", "days":14, "created":true }

L’endpoint envoie par e-mail la clé d’essai à l’adresse (il n’y a pas de clé dans la réponse — SMTP doit être configuré sur l’instance) ; le client saisit ensuite cette clé et la passe à ActivateAsync() comme n’importe quelle autre clé. Elle s’active et se valide exactement comme une clé payante ; info.IsTrial vaut true et DaysRemaining décompte. Flux complet : Essais en libre-service.

5. Passez en production

Les deux modes

• La clé publique embarquée dans le build livré correspond à la clé qui signe les licences de ce produit.
• Le slug Product dans le SDK correspond au produit pour lequel vous émettez des licences (le serveur limite l’activation au produit).
• Choisissez hors ligne ou en ligne (ou les deux) : un fichier hors ligne pour les environnements isolés (air-gapped)/entreprise, l’activation en ligne pour l’application des sièges et la révocation — voir Hors ligne et isolé (air-gapped).
• Sièges et expiration correctement définis sur l’édition/la licence ; testez l’atteinte de la limite de sièges.
• Testez le chemin de révocation (POST /admin/licenses/{id}/revoke) — l’application doit retomber en version gratuite au prochain rafraîchissement de lease. Voir Révoquer, renouveler et expiration.
• Si vous appliquez la couverture des versions, effectuez le rattrapage (backfill) de chaque licence émise avant la couverture (Releases & coverage → Enforcement readiness) avant de livrer un build KeyrightRequireCoverage, et définissez KeyrightCoverageVersion / KeyrightCoverageEntitlementDate depuis votre pipeline de release — Couverture des versions.

Cloud uniquement

• Si vous vendez via une boutique / un Merchant of Record, connectez le traitement des commandes à POST /webhooks/fulfill/{slug} pour que les commandes payées émettent automatiquement des clés — Traitement des commandes de boutique.
• Confirmez que votre plan couvre les nombres de licences actives et de produits que vous attendez (mise à niveau sous Settings → Plan & billing).

Auto-hébergé uniquement

• Ayez un plan de sauvegarde pour la base de données et votre secret de chiffrement des clés — perdre ce secret signifie perdre chaque clé de signature. Sauvegardez aussi la licence de votre propre instance.
• Ayez un plan de rotation de la clé de signature en place.
• Gardez une licence d’instance valide installée — une instance auto-hébergée échoue en mode fermé et cesse de servir les appels runtime une fois que sa propre licence a expiré au-delà de la période de grâce (Licence et éditions).

L’API en un coup d’œil

Domaine	Endpoint	Auth	Rôle
Runtime	POST /v1/activate	aucune	Active une clé sur une machine → lease signée. Corps : { key, machineId, product }
Runtime	POST /v1/validate	aucune	Valide/rafraîchit sans consommer de siège. Corps : { key, machineId, product }
Admin	GET/POST /admin/products, /admin/products/{slug}/tiers	jeton admin	Gérer les produits et niveaux
Admin	POST /admin/products/{slug}/signing-key	jeton admin	Générer/faire tourner la clé de signature d’un produit → signingPublicKey
Admin	POST /admin/licenses, /admin/licenses/{id}/{revoke,renew,transfer,deactivate,offline-lease}	jeton admin	Émettre et gérer les licences
Admin	GET /admin/licenses, /admin/overview, /admin/licenses/{id}/activations	jeton admin	Reporting
Admin	GET /admin/self-license	jeton admin	Auto-hébergement uniquement : le statut de licence de cette instance (édition, phase, jours restants)
Admin	GET/POST /admin/team	jeton owner	Membres de l’équipe
Runtime	POST /v1/coverage	aucune (clé de licence)	La version X est-elle couverte pour cette licence ? — la brique de base de votre propre verrou de téléchargement
Admin	POST /admin/products/{slug}/releases, /admin/licenses/{id}/coverage/{preset,grants}, /admin/products/{slug}/coverage/{readiness,backfill,export,migrate}	jeton admin	Couverture des versions : registre, conditions, rattrapage (backfill), export isolé du réseau
Plateforme	GET/POST /platform/tenants, /platform/plans, /platform/tenants/{id}/signing-key	jeton de plateforme	Opérateur multi-tenant
Auth	POST /auth/login → /auth/mfa, /auth/session, /auth/sso	—	Connexion au tableau de bord → jeton de session

Les corps runtime utilisent machineId (une empreinte stable par machine) et product (le slug du produit) aux côtés de la key de licence — les noms de champs non reconnus sont traités comme une clé inconnue. Les détails complets de requête/réponse par langage se trouvent dans les guides SDK et API HTTP ; les endpoints de couverture sont documentés dans Couverture des versions.

La carte complète des endpoints se trouve dans la référence de l’API HTTP.