Conditionner des fonctionnalités et des éditions

Objectif. Vous voulez que « Export », « SSO », « projets illimités » — toute capacité réservée à Pro ou propre à une édition — s’active depuis la licence du client, vérifiée localement sans appel serveur, et vous voulez changer qui obtient quoi sans livrer une nouvelle version.

Quand l’utiliser

• Utilisez ceci si votre produit a des fonctionnalités qui dépendent du forfait acheté par le client (un niveau gratuit contre un niveau payant, Pro contre Enterprise, des options), et que vous voulez que la décision voyage à l’intérieur de la licence signée, pour qu’elle fonctionne hors ligne et ne puisse pas être basculée en modifiant un fichier de configuration.
• Utilisez ceci si vous vous attendez à ce que votre gamme de forfaits évolue : conditionnez sur des droits nommés plutôt que sur l’édition, et un futur reconditionnement devient une modification dans le tableau de bord, pas une release.
• Pas ceci si ce que vous vendez est de la consommation (rendus, appels d’API, générations d’IA) plutôt qu’une capacité — mesurez-la avec les crédits. Et la couverture des versions du produit qu’une licence peut exécuter est un axe distinct — voir Couverture des versions.

Les droits sont le mécanisme derrière toute cette page : une licence porte une petite carte d’indicateurs nommés et de limites numériques, signée avec le niveau, que votre application relit à l’exécution. Comme ils vivent dans la charge utile signée, une licence divulguée ou modifiée à la main ne peut pas accorder un indicateur que le service n’a jamais signé — la signature échoue et le SDK échoue en mode fermé vers Free.

Ce que vous faites (côté éditeur)

Une édition (le terme du tableau de bord pour un niveau) porte un nombre de sièges et un modèle de droits — les indicateurs nommés et les limites numériques intégrés à chaque licence émise à partir d’elle. Définissez-les une fois par édition ; chaque licence de cette édition en hérite.

Dans le tableau de bord : Products → votre produit → Editions → Add edition (ou modifiez une édition existante), et renseignez les droits — un indicateur booléen comme export, ou une limite numérique comme max-projects. Via l’API, c’est un seul appel :

# définir une édition avec son modèle de droits
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"}}'

# une édition supérieure qui ajoute un indicateur et relève la limite
curl -X POST $BASE/admin/products/acme-app/tiers -H "X-Admin-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"name":"enterprise","seats":25,"entitlements":{"export":"true","sso":"true","max-projects":"unlimited"}}'

Les valeurs de droits sont des chaînes sur le réseau : "true"/"false" pour un indicateur, un entier ou le littéral "unlimited" pour une limite. Quand vous émettez une licence depuis cette édition, le modèle est appliqué automatiquement — la carte de droits apparaît sur la licence (GET /admin/licenses/{id} renvoie un objet entitlements) et à l’intérieur de la lease signée que l’application du client vérifie :

# émettre une licence pro — elle hérite des droits de pro
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"}'

Un client qui a besoin de quelque chose de différent obtient une surcharge par licence à l’émission : passez une carte entitlements explicite dans le corps de POST /admin/licenses (le volet Issue license du tableau de bord expose la même chose dans ses options avancées), pour accorder, par exemple, sso à un seul compte Pro sans inventer une nouvelle édition. La surcharge est intégrée à la charge utile signée de cette seule licence, exactement comme un indicateur de modèle.

Les droits sont figés et signés à l’émission de la licence — il n’existe pas d’appel « modifier les droits d’une clé active », et renvoyer /admin/licenses avec un id existant est rejeté comme doublon. Pour changer ce que débloque une clé déjà émise, émettez au client une nouvelle licence (avec les droits que vous voulez, ou depuis une édition mise à jour) et faites-la lui activer ; l’ancienne clé peut être révoquée une fois la bascule faite. Modifier le modèle d’une édition ne change que les licences émises après la modification.

Dans votre code

Votre application n’embarque que la clé publique et lit les droits sur la licence validée — hors ligne, sans appel serveur (l’activation/Validate() a déjà livré et mis en cache la lease signée). Les détails de l’initialisation du client sont dans le guide du SDK .NET ; voici uniquement le contrôle d’accès, dans chaque SDK et en HTTP brut.

Les droits que vous lisez dans le code sont exactement ceux que le tableau de bord affiche sur une licence — les indicateurs intégrés à l’émission :

.NET

using Keyright.Client;

// Contrôle au niveau de l'édition : IsPaid est vrai pour toute édition au-dessus de Free ; basculez sur l'édition pour les grands niveaux.
LicenseInfo info = License.Validate();          // hors ligne, ne lève jamais d'exception ; les échecs se résolvent en Edition.Free
if (info.IsPaid)      ShowPaidChrome();          // essai OU payant — info.IsTrial les distingue
if (info.Edition == Edition.Enterprise) ShowEnterpriseOnlyPanel();

// Contrôle au niveau de la fonctionnalité : demandez le droit par son nom — c'est la façon durable de conditionner.
if (License.IsEnabled("export"))                 // indicateur booléen ; un indicateur manquant se lit comme false (échec en mode fermé)
    EnableExportCommand();

// Limite numérique : vous passez le repli en mode fermé, donc une valeur absente/corrompue ne peut jamais se lire comme « plus ».
long maxProjects = License.GetLimit("max-projects", fallback: 1);
if (currentProjectCount >= maxProjects)
    PromptToUpgrade();

Node.js

const { info } = license.validate();                        // hors ligne ; les échecs se résolvent en édition 'free'
if (info.isPaid) showPaidChrome();                          // essai OU payant
if (info.edition === 'enterprise') showEnterpriseOnlyPanel();

if (info.entitlements.isEnabled('export')) enableExportCommand();   // indicateur manquant -> false
const maxProjects = info.entitlements.getLimit('max-projects', 1);  // 'unlimited' -> un très grand nombre
if (currentProjectCount >= maxProjects) promptToUpgrade();

Python

from keyright import Edition

info = license.validate_info()                       # hors ligne ; les échecs se résolvent en Edition.FREE
if info.is_paid:
    show_paid_chrome()                               # essai OU payant
if info.edition == Edition.ENTERPRISE:
    show_enterprise_only_panel()

if info.entitlements.is_enabled("export"):           # indicateur manquant -> False
    enable_export_command()
max_projects = info.entitlements.get_limit("max-projects", fallback=1)   # "unlimited" -> très grand entier
if current_project_count >= max_projects:
    prompt_to_upgrade()

Java

LicenseInfo info = client.validateInfo();            // hors ligne ; les échecs se résolvent en Edition.FREE
if (info.isPaid()) showPaidChrome();                 // essai OU payant
if (info.edition == Edition.ENTERPRISE) showEnterpriseOnlyPanel();

if (info.entitlements.isEnabled("export")) enableExportCommand();   // indicateur manquant -> false
long maxProjects = info.entitlements.getLimit("max-projects", 1);   // "unlimited" -> EntitlementSet.MAXLONG
if (currentProjectCount >= maxProjects) promptToUpgrade();

Tout langage (HTTP brut)

# Aucun appel SDK — lisez les indicateurs directement dans la lease que vous avez déjà vérifiée.
# Une fois la signature de la lease validée (voir « Vérifier la lease hors ligne »), le JSON
# signé de la lease porte un objet "entitlements" ; l'indicateur fait partie de la charge utile signée
# (le segment |ent=), donc une lease qui se vérifie est une lease dont vous pouvez faire confiance aux droits :
#
#   "entitlements": { "export": "true", "max-projects": "10" }
#
# export activé    = entitlements["export"] vaut "true"/"1"/"yes"   (absent -> off, échec en mode fermé)
# limite de projets = int(entitlements["max-projects"])             ("unlimited" -> pas de plafond ; absent -> votre repli)

IsEnabled et GetLimit valident chacun sur place et échouent en mode fermé : un indicateur manquant est désactivé, une limite manquante ou impossible à analyser renvoie votre repli, et "unlimited" se lit comme long.MaxValue. Quand vous vérifiez plusieurs droits ensemble, validez une fois et réutilisez le résultat :

LicenseInfo info = License.Validate();
bool canExport = info.Entitlements.IsEnabled("export");
long maxSeats  = info.Entitlements.GetLimit("max-seats", 1);

Ce que LicenseInfo expose pour votre interface : IsPaid, Edition, IsTrial, StatusBadge (p. ex. « Enterprise » / « Pro Trial »), ExpiryUtc, DaysRemaining, Status et un Message destiné aux humains, plus la carte Entitlements elle-même. Conditionnez la fonctionnalité sur le droit ; n’utilisez l’édition que pour l’habillage grossier.

Les consommateurs en HTTP brut (Go, Rust, PHP…) lisent les mêmes droits depuis la lease vérifiée : le JSON signé de la lease porte un objet entitlements, et une fois la signature de la lease vérifiée, vous lisez les indicateurs directement dedans. Les droits font partie de la charge utile signée canonique (le segment |ent=), donc une lease qui se vérifie est une lease dont vous pouvez faire confiance aux droits — la recette de vérification complète est dans Utiliser l’API HTTP directement.

Changer ce qu’obtient un client existant. Modifier le modèle d’une édition ne change que les futures licences — les licences émises conservent les droits avec lesquels elles ont été signées, la même règle d’instantané que celle utilisée par la couverture. Pour changer une licence déjà en circulation, vous avez deux chemins confirmés : ajouter une surcharge par licence (réémettre la licence depuis sa page du tableau de bord / POST /admin/licenses avec le même id), ce qui la re-signe avec la nouvelle carte de droits et le client la récupère au prochain rafraîchissement de lease ; ou, pour toute une édition, modifier le modèle et réémettre les licences concernées. Un renouvellement prolonge la durée et re-signe, mais se limite à l’expiration et aux sièges — la réémission est le chemin quand c’est l’ensemble de droits lui-même qui doit changer.

Cloud ou auto-hébergé

Les droits fonctionnent à l’identique dans les deux modes — même modèle, mêmes appels SDK, même charge utile signée. Les seules différences sont les habituelles :

• $BASE et $TOKEN. Cloud : https://keyright.delta1labs.com avec un jeton d’équipe/de session. Auto-hébergé : l’URL de votre instance avec votre KEYRIGHT_ADMIN_TOKEN.
• Les droits que vous pouvez distribuer dépendent de votre propre forfait (Cloud) ou de votre édition auto-hébergée — les noms de droits sont à vous d’inventer et signifient ce que votre application décide ; il n’y a pas de vocabulaire fixe. (À ne pas confondre avec les droits de la licence propre de l’instance, qui conditionnent des fonctionnalités de Keyright comme le SSO — voir Licences et éditions.)

Vérifier

1. Définissez une édition pro avec {"export":"true"} et un produit sans free ; émettez-vous une clé pro.
2. Avant l’activation, Validate() renvoie Free et IsEnabled("export") vaut false — la commande reste masquée.
3. Activez la clé. Le badge passe à Pro, IsEnabled("export") renvoie true, et la commande d’export apparaît. Coupez le réseau et redémarrez — la décision tient toujours depuis la lease en cache, ce qui prouve qu’elle est hors ligne.
4. Ajoutez "sso":"true" à l’édition (ou passez-le comme surcharge par licence) et émettez une nouvelle licence à partir d’elle ; activez cette clé et rafraîchissez — le nouvel indicateur apparaît sans nouvelle version de l’application. (Les droits sont figés sur la clé d’origine à l’émission, donc il s’agit d’une nouvelle clé, pas d’une modification de l’ancienne.)
5. Modifiez à la main un fichier de lease en cache (basculez un indicateur) et revalidez : la signature échoue et l’application retombe en Free, confirmant que le contrôle ne peut pas être falsifié.

Voir aussi

• Intégration du SDK .NET — le parcours client complet sur lequel ces extraits s’appuient.
• Utiliser l’API HTTP directement — lire les droits depuis une lease vérifiée dans n’importe quel langage.
• Sécurité et modèle de lease — pourquoi un droit signé ne peut être ni falsifié ni modifié.
• Révoquer, renouveler et gérer l’expiration — les autres choses que vous changez sur une licence active.
• Crédits et usage mesuré — conditionner la consommation plutôt qu’une capacité.