API de licences — Démarrage rapide

URL de base : https://api.xp-flightdeck.com/licenses-api/v1

À quoi sert cette API

Émettre et valider des jetons de licence de courte durée liés à l'email d'un utilisateur final et à son appareil. Cette API est multi-éditeur : chaque éditeur (studio de jeu, SaaS, éditeur de logiciel) a ses propres tokens et ne voit jamais que ses propres données. Les admins d'un éditeur peuvent créer des licences, les lister, les activer/désactiver et désactiver des appareils — le tout scopé à leur propre compte.

Authentification

Chaque requête doit inclure l'en-tête correspondant à son palier — les tokens de chaque éditeur lui sont propres, générés une fois à la création de son compte : - Côté client : X-Client-Token: <token> — le token client de votre éditeur - Côté admin : X-Admin-Token: <token> — le token admin de votre éditeur - Côté plateforme : X-Platform-Token: <token> — réservé à l'opérateur, provisionne les comptes éditeur

En cas d'échec : 401 {"detail":"invalid client/admin/platform token"}.

Concepts clés

Format de clé de licence : XXXX-XXXX-XXXX (A–Z sans O/I, chiffres 2–9).
Lien appareil : une activation est enregistrée par device_hash + device_name.
Quota : chaque licence applique max_activations par utilisateur final ; au-delà, réponse 409 avec les compteurs.
Débit limité : /activate est throttlé par (éditeur, email) — un 429 signifie trop de tentatives pour cet utilisateur final précis, pas pour tout l'éditeur.
Jeton court-terme : /activate renvoie un JSON + signature Ed25519 (sig) + un identifiant de clé (kid). Utilisez /public-keys pour vérifier.
Rotation de clé : la clé de signature peut être remplacée par l'opérateur de la plateforme sans invalider les jetons déjà émis — récupérez toujours la clé publique correspondant au kid du jeton, ne codez pas en dur une seule clé.

Structure du jeton (renvoyé par `/activate`)

{
  "token": {
    "publisher": "votre-slug-editeur",
    "kid": "a1b2c3d4",
    "product": "VotreProduit",
    "edition": "Pro",
    "features": ["featA", "featB"],
    "license_ref": "GH45",
    "email": "pilote@example.com",
    "max_activations": 3,
    "activations_count": 1,
    "issued_at": "2025-09-01T10:00:00+00:00",
    "expires_at": "2025-09-01T11:00:00+00:00",
    "device": { "hash": "sha256-de-lappareil", "name": "Mon PC" },
    "sig": "signature-ed25519-base64"
  },
  "mode": "full"
}

Vérifiez le jeton en récupérant GET /public-keys, en choisissant l'entrée dont le kid correspond à celui du jeton, puis en vérifiant la signature sur les octets UTF-8 du payload JSON (sans le champ sig). Vous pouvez aussi vérifier que token.publisher correspond à votre propre slug — la clé de signature est partagée par toute la plateforme, la signature seule prouve l'authenticité, pas que le jeton vous était destiné.

Démarrage rapide cURL (client)

Activer (champs obligatoires : email, license_key, device_hash, device_name) :

curl -sS -X POST   -H "X-Client-Token: $CLIENT_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/activate   -d '{
        "email":"pilote@example.com",
        "license_key":"ABCD-EF23-GH45",
        "device_hash":"<sha256>",
        "device_name":"Mon PC"
      }'

Désactiver (obligatoires : license_key_hash, device_hash) :

curl -sS -X POST   -H "X-Client-Token: $CLIENT_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/deactivate   -d '{
        "license_key_hash":"<64-hex>",
        "device_hash":"<sha256>"
      }'

Démarrage rapide cURL (admin)

Créer une licence (obligatoires : email, product, edition, max_activations ; optionnel : features) :

curl -sS -X POST   -H "X-Admin-Token: $ADMIN_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/admin/licenses   -d '{
        "email":"pilote@example.com",
        "product":"VotreProduit",
        "edition":"Pro",
        "max_activations":3,
        "features":["featA","featB"]
      }'

Lister les licences (tous facultatifs : email, product, edition, enabled, limit, offset ; réponse { items, total }) :

curl -sS   -H "X-Admin-Token: $ADMIN_TOKEN"   "https://api.xp-flightdeck.com/licenses-api/v1/admin/licenses?email=pilote@example.com&enabled=true&limit=50&offset=0"

Activer/désactiver (obligatoires : license_key, enabled, email) :

curl -sS -X POST   -H "X-Admin-Token: $ADMIN_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/admin/licenses/enable   -d '{
        "license_key":"ABCD-EF23-GH45",
        "enabled":true,
        "email":"pilote@example.com"
      }'

Forcer la désactivation d'un appareil (obligatoires : license_key, device_hash, email) :

curl -sS -X POST   -H "X-Admin-Token: $ADMIN_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/admin/deactivate-device   -d '{
        "license_key":"ABCD-EF23-GH45",
        "device_hash":"<sha256>",
        "email":"pilote@example.com"
      }'

Démarrage rapide cURL (plateforme — opérateur uniquement)

Créer un éditeur (obligatoires : name, slug ; renvoie client_token/admin_token une seule fois) :

curl -sS -X POST   -H "X-Platform-Token: $PLATFORM_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/platform/publishers   -d '{
        "name":"Votre Studio",
        "slug":"votre-studio"
      }'

Faire tourner un token d'éditeur (obligatoires : slug, which : client ou admin) :

curl -sS -X POST   -H "X-Platform-Token: $PLATFORM_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/platform/publishers/rotate-token   -d '{
        "slug":"votre-studio",
        "which":"client"
      }'