Référence
Référence de l'API HTTP
Une carte lisible de l'API HTTP du service d'émission, regroupée par domaine — Runtime, Admin, Plateforme, Auth, Plans, Webhooks — avec la méthode, le chemin et le mode d'authentification de chaque endpoint.
Une carte lisible de l’API HTTP du service d’émission, regroupée par domaine. Cette page sert à trouver le bon endpoint et à savoir comment il est authentifié ; la spécification OpenAPI lisible par machine est livrée avec le service pour les schémas complets de requête/réponse, les types de champs et les exemples.
$BASE est l’URL de votre service d’émission (p. ex. https://keyright.delta1labs.com).
L’authentification en un coup d’œil
Chaque endpoint hors runtime est protégé par l’un de ces mécanismes. Toute l’authentification admin/plateforme utilise l’en-tête X-Admin-Token (un jeton de session issu de la connexion au tableau de bord se présente de la même façon).
| Auth | En-tête(s) | Qui |
|---|---|---|
| aucune | — | les appels runtime du client final (activation, validation, essai) |
| jeton de tenant | X-Admin-Token: <jeton d'équipe/de session/admin d'environnement> | un éditeur qui gère son propre tenant |
| jeton de plateforme | X-Admin-Token: <KEYRIGHT_PLATFORM_TOKEN> (+ X-Tenant pour /admin/*) | l’opérateur de la plateforme |
| session | X-Admin-Token: <jeton de session issu de /auth/*> | un utilisateur connecté au tableau de bord |
| HMAC | X-Keyright-Signature | les webhooks des fournisseurs de paiement |
| secret cron | X-Cron-Secret | le planificateur externe de notifications |
Les rôles derrière un jeton de tenant sont limités par capacité (owner ⊃ admin ⊃ support/billing ⊃ viewer) ; le rôle minimal d’un endpoint est indiqué ci-dessous lorsque cela compte. Voir Tableau de bord d’administration pour le modèle de rôles.
Runtime (/v1/*) — sans authentification, appelé par votre application / vos clients
| Méthode | Chemin | Rôle |
|---|---|---|
| POST | /v1/activate | Active une clé sur une machine → consomme un siège, renvoie une lease signée. Corps : { key, machineId, product }. |
| POST | /v1/validate | Revalide / rafraîchit une clé+machine sans consommer de nouveau siège. Corps : { key, machineId, product }. |
| POST | /v1/free-seat | Libère le siège que cette machine détient sur une clé. Corps : { key, machineId, product }. |
| POST | /v1/trial | Essai en libre-service : génère une clé d’essai pour un produit et l’envoie par e-mail (idempotent par e-mail — une nouvelle demande renvoie la clé existante). Corps { product, email, company }. La réponse JSON confirme { ok, trial, emailed, expiresUtc, days, created } et ne contient pas la clé. CORS ouvert. Voir Essais gratuits en libre-service. |
| POST | /v1/coverage | Cette licence couvre-t-elle un build donné ? Renvoie l’éligibilité + status (Covered / NotCovered / NotConfigured) + newestCovered. Corps { key, product, version, on, channel }. Le bloc de couverture signé voyage normalement avec activate/validate ; ceci est la vérification explicite. Voir Couverture des versions. |
Admin (/admin/*) — jeton de tenant
Gérez les produits, les licences et l’équipe d’un tenant. Avec le jeton de plateforme, ces endpoints exigent un en-tête X-Tenant désignant le tenant cible.
Produits et niveaux (tiers)
| Méthode | Chemin | Rôle |
|---|---|---|
| GET | /admin/products | Liste les produits (avec niveaux, nombre de licences, paramètres d’essai). |
| POST | /admin/products | Crée/met à jour un produit (nom, slug, trialDays/trialTier/trialSeats facultatifs). |
| POST | /admin/products/{slug}/trial | Active/désactive l’essai en libre-service d’un produit. Corps { days, tier, seats } (days <= 0 désactive) ; la réponse les renvoie sous la forme { trialDays, trialTier, trialSeats }. |
| POST | /admin/products/{slug}/tiers | Crée/met à jour un niveau propre au produit (sièges + modèle de droits). |
| POST | /admin/products/{slug}/signing-key | Génère (ou, avec {"rotate":true}, fait tourner) la clé de signature propre à ce produit → renvoie signingPublicKey à embarquer dans votre application. |
| GET | /admin/tiers | Liste les modèles de niveaux à l’échelle du tenant. |
| POST | /admin/tiers | Crée/met à jour un modèle de niveau à l’échelle du tenant. |
Licences
| Méthode | Chemin | Rôle |
|---|---|---|
| POST | /admin/licenses | Émet une licence (génère automatiquement une clé sauf si vous passez id). |
| GET | /admin/licenses[?product=] | Liste/filtre les licences. |
| POST | /admin/licenses/{id}/revoke | Révoque une licence (prend effet à la prochaine vérification en ligne). |
| POST | /admin/licenses/{id}/renew | Prolonge l’expiration / modifie les sièges, sans nouvelle clé. |
| POST | /admin/licenses/{id}/transfer | Transfère la propriété à un nouveau titulaire (historique audité). |
| GET | /admin/licenses/{id}/transfers | La chaîne de propriété de la licence. |
| POST | /admin/licenses/{id}/deactivate | Libère le siège d’une machine précise. |
| POST | /admin/licenses/{id}/offline-lease | Signe une lease hors ligne pour un identifiant de machine isolée du réseau (air-gapped). |
| GET | /admin/licenses/{id}/activations | Les machines sur lesquelles une licence est active (métadonnées d’appareil + géolocalisation). |
| POST | /admin/licenses/bulk-revoke | Révoque plusieurs licences par id, résultats par élément. |
| POST | /admin/licenses/bulk-seats | Modifie les nombres de sièges en masse, résultats par élément. |
| GET | /admin/revocation-list | Construit + signe une liste de révocation hors ligne distribuable. |
Couverture des versions — quelles versions une licence couvre. Voir Couverture des versions pour le guide complet, la forme des champs et le côté SDK.
| Méthode | Chemin | Rôle |
|---|---|---|
| GET | /admin/licenses/{id}/coverage | La couverture d’une licence : indicateur de configuration, mode, octrois, fin de support. |
| POST | /admin/licenses/{id}/coverage/grants | Ajoute un octroi — une plage de versions et/ou une fenêtre de dates. |
| POST | /admin/licenses/{id}/coverage/preset | Applique un préréglage (lifetime, updates-for-period, one-major, one-major + upgrade-protection, subscription, subscription-with-fallback) qui se développe en octrois. |
| POST | /admin/licenses/{id}/coverage/mode | Définit le mode d’application : enforced ou unenforced. |
| POST | /admin/licenses/{id}/coverage/revoke | Révoque un octroi. |
| GET | /admin/licenses/{id}/coverage/check[?version=&on=&channel=] | Évalue un build par rapport à cette licence (Covered / NotCovered / NotConfigured, avec la raison). |
| GET | /admin/licenses/{id}/coverage/block | Le bloc de couverture signé de cette licence (pour import hors ligne / isolé du réseau). |
| GET | /admin/products/{slug}/releases | Liste les versions enregistrées d’un produit. |
| POST | /admin/products/{slug}/releases | Enregistre une version (version, date d’éligibilité, canal) — alimente les aperçus de couverture et la version couverte la plus récente. |
| GET | /admin/products/{slug}/releases/preview | Nombre de licences couvertes / non couvertes / non configurées sur l’ensemble des licences du produit. |
| GET | /admin/products/{slug}/coverage/readiness | Combien de licences n’ont pas encore de couverture — le verrou d’activation avant d’appliquer. |
| POST | /admin/products/{slug}/coverage/backfill | Donne aux anciennes licences un octroi legacy (à vie, fin de support ou lignes CSV) pour que l’application ne les exclue jamais. |
| POST | /admin/products/{slug}/coverage/migrate[?dryRun=] | Applique un octroi à l’ensemble des licences d’un produit ; dryRun prévisualise le gain. |
| GET | /admin/products/{slug}/coverage/export | Exporte en masse le bloc de couverture signé de chaque licence pour une livraison isolée du réseau. |
Un client peut lire sa propre couverture depuis le portail en libre-service : GET /portal/license/{id}/coverage (jeton de lien magique du portail) → la phrase de statut en langage clair + la fin de support.
Équipe
| Méthode | Chemin | Auth | Rôle |
|---|---|---|---|
| GET/POST | /admin/team | owner | Liste / invite des membres de l’équipe (l’invitation envoie par e-mail un jeton à usage unique). |
| POST | /admin/team/{id} | owner | Active/désactive un membre. |
| POST | /admin/team/{id}/set-password | owner | Provisionne le mot de passe de tableau de bord d’un membre. |
Espace de travail, reporting et intégration
| Méthode | Chemin | Rôle |
|---|---|---|
| GET | /admin/overview | Tableau de bord d’accueil : résumé d’abonnement, compteurs, répartition par produit, tendance, renouvellements à venir. |
| GET | /admin/account | Tenant + plan + usage + le bloc integration (URL de base, clé publique de signature, URL de webhook). |
| GET | /admin/stats | Totaux par produit (licences, sièges actifs, expirations prochaines, révoquées). |
| GET | /admin/usage | Sièges alloués/utilisés par licence + totaux (facturation à l’usage). |
| GET | /admin/export[?product=] | Ensemble complet licences + activations. |
| GET | /admin/audit | Journal d’audit attribuable des actions de modification. |
| GET | /admin/public-key | La clé publique de signature du tenant. null tant qu’aucune clé de tenant n’existe — pour une clé par produit, utilisez plutôt POST /admin/products/{slug}/signing-key. |
| GET | /admin/self-license | Auto-hébergement uniquement : le statut de licence de cette instance — status, edition, isTrial, phase (active/expiring/grace/gated), daysUntilExpiry, graceDaysLeft. |
| POST | /admin/workspace | Propriétaire : nom de l’espace de travail, logo, indicateur d’onboarding. |
| POST | /admin/webhook-secret/rotate | Propriétaire : fait tourner le secret du webhook de traitement des commandes de ce tenant. |
| POST | /admin/billing/checkout | Propriétaire : ouvre un paiement Lemon Squeezy pour mettre le plan à niveau. |
| POST/GET | /admin/resellers, /admin/resellers/{id} | Gère les revendeurs (émetteurs plafonnés, limités à un produit). |
Plateforme (/platform/*) — jeton de plateforme
La surface opérateur multi-tenant. Désactivée (503) lorsque KEYRIGHT_PLATFORM_TOKEN n’est pas défini (auto-hébergement mono-tenant).
| Méthode | Chemin | Rôle |
|---|---|---|
| POST | /platform/tenants | Crée une société/un tenant → renvoie le jeton initial du propriétaire, la clé publique de signature, le secret de webhook. |
| GET | /platform/tenants[?slug=] | Liste les tenants. |
| POST | /platform/tenants/{id} | Active/désactive, définit le plan, le statut d’abonnement. |
| POST | /platform/tenants/{id}/signing-key | Importe (PKCS#8 de Nebula) ou génère une clé de signature de tenant. |
| POST | /platform/tenants/{id}/rotate-signing-key | Fait tourner la clé de signature d’un tenant. |
| POST | /platform/tenants/{id}/rotate-webhook-secret | Fait tourner le secret de webhook d’un tenant. |
| GET | /platform/plans | Catalogue complet des plans (y compris les plans non publics). |
| POST | /platform/plans/{key} | Crée/met à jour la tarification, les quotas et les fonctionnalités d’un plan. |
Auth (/auth/*) — connexion au tableau de bord → jeton de session
Ces endpoints émettent un jeton de session que vous présentez ensuite en X-Admin-Token aux endpoints /admin/* ci-dessus. La connexion se fait par tenant (passez X-Tenant ; par défaut default).
| Méthode | Chemin | Rôle |
|---|---|---|
| POST | /auth/login | E-mail + mot de passe → un défi MFA. |
| POST | /auth/mfa | E-mail + mot de passe + code TOTP → jeton de session. |
| POST | /auth/sso | Échange un jeton d’identité OIDC validé contre un jeton de session. |
| POST | /auth/session | Échange un jeton d’accès de connexion native / sociale contre un jeton de session. |
| GET | /auth/oauth/{provider} → /auth/oauth/{provider}/callback | OAuth natif Google / GitHub sur votre propre domaine. |
Plans (/plans) — public
| Méthode | Chemin | Auth | Rôle |
|---|---|---|---|
| GET | /plans | aucune | Catalogue public de tarification (plans marqués publics), pour une page de tarifs ou une inscription. |
Webhooks (/webhooks/*) — HMAC
Déclencheurs de traitement des commandes : un fournisseur de paiement (ou un adaptateur léger) envoie en POST un événement normalisé, signé en HMAC sur le corps brut dans X-Keyright-Signature. « Payé » génère une licence (idempotent par référence de commande) ; « remboursement »/« annulation » la révoque. Le traitement du paiement lui-même est hors périmètre.
| Méthode | Chemin | Rôle |
|---|---|---|
| POST | /webhooks/fulfill/{slug} | Webhook par tenant ; le tenant est tiré de la route et vérifié avec le secret de ce tenant. |
| POST | /webhooks/fulfill | Ancien webhook à l’échelle du déploiement (mono-tenant, KEYRIGHT_WEBHOOK_SECRET). |
Opérationnel
| Méthode | Chemin | Auth | Rôle |
|---|---|---|---|
| GET | /health | aucune | Sonde de vivacité/version. |
| GET | /branding | aucune | Nom de marque/logo/couleur en marque blanche pour toute interface. |
| POST | /internal/notifications/run | secret cron | Exécute l’analyse quotidienne des expirations/limites de sièges (pilotez-la depuis un planificateur externe). |
| divers | /portal/* | lien magique | Portail client en libre-service (consulter les licences, retélécharger la clé/le fichier, libérer des sièges). |
Le tableau de bord lui-même est servi à /dashboard — voir Tableau de bord d’administration.