Skip to content

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).

AuthEn-tête(s)Qui
aucune—les appels runtime du client final (activation, validation, essai)
jeton de tenantX-Admin-Token: <jeton d'équipe/de session/admin d'environnement>un éditeur qui gère son propre tenant
jeton de plateformeX-Admin-Token: <KEYRIGHT_PLATFORM_TOKEN> (+ X-Tenant pour /admin/*)l’opérateur de la plateforme
sessionX-Admin-Token: <jeton de session issu de /auth/*>un utilisateur connecté au tableau de bord
HMACX-Keyright-Signatureles webhooks des fournisseurs de paiement
secret cronX-Cron-Secretle 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éthodeCheminRôle
POST/v1/activateActive une clé sur une machine → consomme un siège, renvoie une lease signée. Corps : { key, machineId, product }.
POST/v1/validateRevalide / rafraîchit une clé+machine sans consommer de nouveau siège. Corps : { key, machineId, product }.
POST/v1/free-seatLibère le siège que cette machine détient sur une clé. Corps : { key, machineId, product }.
POST/v1/trialEssai 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/coverageCette 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éthodeCheminRôle
GET/admin/productsListe les produits (avec niveaux, nombre de licences, paramètres d’essai).
POST/admin/productsCrée/met à jour un produit (nom, slug, trialDays/trialTier/trialSeats facultatifs).
POST/admin/products/{slug}/trialActive/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}/tiersCrée/met à jour un niveau propre au produit (sièges + modèle de droits).
POST/admin/products/{slug}/signing-keyGénère (ou, avec {"rotate":true}, fait tourner) la clé de signature propre à ce produit → renvoie signingPublicKey à embarquer dans votre application.
GET/admin/tiersListe les modèles de niveaux à l’échelle du tenant.
POST/admin/tiersCrée/met à jour un modèle de niveau à l’échelle du tenant.

Licences

MéthodeCheminRô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}/revokeRévoque une licence (prend effet à la prochaine vérification en ligne).
POST/admin/licenses/{id}/renewProlonge l’expiration / modifie les sièges, sans nouvelle clé.
POST/admin/licenses/{id}/transferTransfère la propriété à un nouveau titulaire (historique audité).
GET/admin/licenses/{id}/transfersLa chaîne de propriété de la licence.
POST/admin/licenses/{id}/deactivateLibère le siège d’une machine précise.
POST/admin/licenses/{id}/offline-leaseSigne une lease hors ligne pour un identifiant de machine isolée du réseau (air-gapped).
GET/admin/licenses/{id}/activationsLes machines sur lesquelles une licence est active (métadonnées d’appareil + géolocalisation).
POST/admin/licenses/bulk-revokeRévoque plusieurs licences par id, résultats par élément.
POST/admin/licenses/bulk-seatsModifie les nombres de sièges en masse, résultats par élément.
GET/admin/revocation-listConstruit + 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éthodeCheminRôle
GET/admin/licenses/{id}/coverageLa couverture d’une licence : indicateur de configuration, mode, octrois, fin de support.
POST/admin/licenses/{id}/coverage/grantsAjoute un octroi — une plage de versions et/ou une fenêtre de dates.
POST/admin/licenses/{id}/coverage/presetApplique 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/modeDéfinit le mode d’application : enforced ou unenforced.
POST/admin/licenses/{id}/coverage/revokeRé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/blockLe bloc de couverture signé de cette licence (pour import hors ligne / isolé du réseau).
GET/admin/products/{slug}/releasesListe les versions enregistrées d’un produit.
POST/admin/products/{slug}/releasesEnregistre 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/previewNombre de licences couvertes / non couvertes / non configurées sur l’ensemble des licences du produit.
GET/admin/products/{slug}/coverage/readinessCombien de licences n’ont pas encore de couverture — le verrou d’activation avant d’appliquer.
POST/admin/products/{slug}/coverage/backfillDonne 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/exportExporte 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éthodeCheminAuthRôle
GET/POST/admin/teamownerListe / invite des membres de l’équipe (l’invitation envoie par e-mail un jeton à usage unique).
POST/admin/team/{id}ownerActive/désactive un membre.
POST/admin/team/{id}/set-passwordownerProvisionne le mot de passe de tableau de bord d’un membre.

Espace de travail, reporting et intégration

MéthodeCheminRôle
GET/admin/overviewTableau de bord d’accueil : résumé d’abonnement, compteurs, répartition par produit, tendance, renouvellements à venir.
GET/admin/accountTenant + plan + usage + le bloc integration (URL de base, clé publique de signature, URL de webhook).
GET/admin/statsTotaux par produit (licences, sièges actifs, expirations prochaines, révoquées).
GET/admin/usageSièges alloués/utilisés par licence + totaux (facturation à l’usage).
GET/admin/export[?product=]Ensemble complet licences + activations.
GET/admin/auditJournal d’audit attribuable des actions de modification.
GET/admin/public-keyLa 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-licenseAuto-hébergement uniquement : le statut de licence de cette instance — status, edition, isTrial, phase (active/expiring/grace/gated), daysUntilExpiry, graceDaysLeft.
POST/admin/workspacePropriétaire : nom de l’espace de travail, logo, indicateur d’onboarding.
POST/admin/webhook-secret/rotatePropriétaire : fait tourner le secret du webhook de traitement des commandes de ce tenant.
POST/admin/billing/checkoutProprié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éthodeCheminRôle
POST/platform/tenantsCré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-keyImporte (PKCS#8 de Nebula) ou génère une clé de signature de tenant.
POST/platform/tenants/{id}/rotate-signing-keyFait tourner la clé de signature d’un tenant.
POST/platform/tenants/{id}/rotate-webhook-secretFait tourner le secret de webhook d’un tenant.
GET/platform/plansCatalogue 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éthodeCheminRôle
POST/auth/loginE-mail + mot de passe → un défi MFA.
POST/auth/mfaE-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}/callbackOAuth natif Google / GitHub sur votre propre domaine.

Plans (/plans) — public

MéthodeCheminAuthRôle
GET/plansaucuneCatalogue 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éthodeCheminRô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/fulfillAncien webhook à l’échelle du déploiement (mono-tenant, KEYRIGHT_WEBHOOK_SECRET).

Opérationnel

MéthodeCheminAuthRôle
GET/healthaucuneSonde de vivacité/version.
GET/brandingaucuneNom de marque/logo/couleur en marque blanche pour toute interface.
POST/internal/notifications/runsecret cronExécute l’analyse quotidienne des expirations/limites de sièges (pilotez-la depuis un planificateur externe).
divers/portal/*lien magiquePortail 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.