API de licence

Voici l’API de ce site — celle qui émet et vérifie les licences. Elle est distincte de l’API de votre propre instance, et vous l’appelez rarement à la main : DockBoard s’active et se renouvelle tout seul.

Elle compte dans un cas : vous vendez ou provisionnez DockBoard pour d’autres, et vous voulez qu’une machine démarre déjà licenciée, sans intervention humaine.

Les surfaces

Cette page traite de la deuxième.

Jetons machine

Un jeton machine est un secret porteur sans session, sans second facteur, sans humain à l’autre bout. Il se place dans une variable de CI, un panneau d’hébergeur, un script cloud-init. Frappez-le dans Admin → Jetons, ou via l’API avec une session staff :

curl -X POST https://licenses.example.com/api/admin/machine-tokens \
  -H "Authorization: Bearer $STAFF_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OVH provisioning",
    "permissions": [
      "customers:view", "customers:manage",
      "subscriptions:view", "subscriptions:manage",
      "licenses:view", "licenses:manage",
      "plans:view", "instances:view", "instances:manage"
    ]
  }'

Les permissions inconnues ou interdites sont écartées à la frappe ; si rien de valide ne subsiste, la frappe est refusée plutôt que de produire un jeton plus faible que demandé. Les routes de jetons sont elles-mêmes réservées aux sessions, pour la même raison que la gestion des clés : un jeton qui frappe des jetons survit à sa propre révocation.

Ce qu’un jeton machine ne peut jamais détenir

La liste d’interdiction est appliquée à trois endroits, pas un : à la frappe, à la résolution, et à la porte de chaque requête. Un jeton antérieur à une modification de la liste n’en tire aucun bénéfice.

Ce qui borne un jeton

Un jeton machine n’a pas de session qui expire, ni d’humain pour remarquer qu’il traîne encore. Trois limites tiennent lieu de l’attention qu’il ne recevra jamais.

Une liste d’adresses sources

allowedIps — une IP ou une plage CIDR par entrée, les deux familles. Présenté depuis ailleurs, il est refusé. La correspondance est fermée par défaut : un appel dont l’adresse source est indéterminable est refusé aussi, car une implémentation qui les laisserait passer désactiverait le contrôle partout d’un coup. Une règle malformée est un 400 à la frappe plutôt qu’un blocage à 3 h du matin, et 0.0.0.0/0 est refusé net — cela se lit comme une restriction et n’en est pas une. Laissez le champ vide et le jeton est joignable de partout, ce qui est la valeur par défaut.

Une expiration qui veut dire quelque chose

Facultative en général — la clé de provisionnement d’un hébergeur est faite pour survivre à une fenêtre de rotation — mais obligatoire, et plafonnée à 90 jours, pour `versions:manage` : ce jeton adoube la version vers laquelle toutes les installations se mettent à jour, et l’avoir immortel dans un coffre de CI en fait la cible la plus précieuse de la plateforme. Préférez GitHub OIDC, qui ne stocke aucun secret. Toute expiration que vous fixez doit être future et à moins de 365 jours : une date passée frappe une clé morte-née, et 2099-01-01 est un « jamais » déguisé en politique de rotation.

Un plafond sur le nombre

50 jetons vivants par installation. Les lignes révoquées ou expirées ne comptent pas — c’est de l’historique d’audit, et les compter bloquerait une installation qui fait tourner ses clés, précisément le comportement que la règle des 90 jours ci-dessus cherche à imposer.

{
  "name": "OVH provisioning",
  "permissions": ["licenses:manage", "customers:manage"],
  "allowedIps": ["203.0.113.0/24", "2001:db8::/32"],
  "expiresAt": "2027-02-17T00:00:00.000Z"
}

La liste dans Admin → Jetons affiche l’allowlist de chaque jeton, et lastUsedIp à côté de lastUsedAt — « d’où s’en sert-on ? » est la question qu’on se pose devant un jeton que personne ne reconnaît, et c’était celle à laquelle la liste ne savait pas répondre.

Provisionnement : un appel, une machine licenciée

curl -X POST https://licenses.example.com/api/admin/provisioning \
  -H "Authorization: Bearer $DOCKBOARD_MACHINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "planSlug": "pro",
    "seats": 1,
    "reference": "order-12345"
  }'

{
  "created": true,
  "customer":     { "id": "…", "email": "customer@example.com", "created": true },
  "subscription": { "id": "…", "planSlug": "pro", "seats": 1, "status": "ACTIVE" },
  "license":      { "id": "…", "keyId": "lic_…", "expiresAt": "2027-08-17T…" },
  "licenseKey":   "eyJ…",
  "installCommand": "curl -fsSL https://get.dockboard.io/install.sh | sudo DOCKBOARD_LICENSE_KEY='eyJ…' sh"
}

Passez installCommand à cloud-init et la machine du client démarre déjà licenciée — il ne voit jamais Admin → Licence. Voir installer DockBoard pour ce qui se passe à l’arrivée.

`reference` fait tout le dessein

Les trois étapes que compose cet appel — compte, abonnement, licence — existent chacune séparément. Elles sont fusionnées ici parce que l’intérêt n’est aucune des trois : c’est que la séquence doit pouvoir être rejouée sans danger.

Un webhook qui redélivre. Une étape de pipeline rejouée. Un panneau où quelqu’un clique deux fois. Sans clé pour reconnaître la répétition, chacun de ces cas facture un second abonnement au client et frappe une seconde licence — et comme émettre révoque la précédente, l’installation en service du client tourne alors silencieusement sur une clé révoquée.

• Le contrôle de rejeu s’exécute en premier, avant toute création : une nouvelle tentative est une simple lecture.
• Il renvoie la licence active actuelle de l’abonnement, pas celle que l’appel avait frappée à l’origine — un changement de formule ou un renouvellement remplace l’ancienne clé, et un hébergeur relisant sa référence doit obtenir celle qui fonctionne aujourd’hui.
• created: false dans la réponse signale un rejeu, et le journal d’audit l’enregistre comme tel plutôt que comme un provisionnement.

Ce qu’un jeton peut atteindre

Deux entrées méritent une note. GET /api/admin/licenses/:id/key renvoie le jeton de licence signé lui-même, et est ouvert aux jetons machine à dessein — un appel de provisionnement incapable de relire la clé qu’il vient d’émettre ne peut rien installer. Chaque lecture est auditée, pour une session comme pour un jeton : c’est ce contrôle qui la rend sûre. Et POST /api/admin/instances/:id/deactivate libère le créneau d’activation qu’une VM reconstruite occupe encore : sans lui, un hébergeur qui recycle ses machines a des clients dont la prochaine installation est refusée pour un serveur qui n’existe plus.

Tout ce qui est hors de ce tableau — personnel, réglages, clés de signature, remboursements — répond à un jeton :

{
  "statusCode": 403,
  "message": "This endpoint is not available to machine tokens. Use a staff session."
}

Erreurs

Exploiter un jeton machine suit les mêmes règles que l’exploitation d’une clé API : rotation par recouvrement, lastUsedAt comme signal de vie et non comme journal d’accès, et en cas de fuite révoquer d’abord, lire le journal d’audit ensuite.