API de Licences

L’API de Licences te permet de créer des politiques de licence, d’émettre des clés, de les valider à l’exécution, de gérer les sièges et les appareils, et d’automatiser l’émission de clés à partir de webhooks de paiement. Elle prend en charge la validation en ligne, le mode hors connexion par JWT, et les modes hybrides.

Deux audiences, deux niveaux d’authentification :

Audience	Authentification	Endpoints
Ton application / SDK (exécution)	Pas de Bearer token requis	`/validate`, `/activate`, `/deactivate`, `/usage`, `/revocation-list`
Admin / Console (gestion)	Bearer token + permission	Tous les autres

Tous les endpoints nécessitent l’en-tête x-tenant.

Politiques

Les politiques définissent ce que confère une licence — fonctionnalités, sièges, appareils, expiration, format de clé et mode de validation.

GET/api/licensing/policiesRequires: manage:license-policies

Lister toutes les politiques pour le tenant courant. Supporte la pagination et la recherche.

Paramètres de requête

Paramètre	Type	Description
`page`	`number`	Numéro de page (par défaut : 1)
`limit`	`number`	Éléments par page (par défaut : 20)
`search`	`string`	Filtrer par nom ou slug

Réponse en cas de succès


{
  "success": true,
  "data": [
    {
      "id": "pol_abc123",
      "name": "Pro Plan",
      "slug": "pro-plan",
      "validationMode": "HYBRID",
      "isActive": true,
      "offlineGraceDays": 7,
      "revocationTtlMin": 60,
      "dimensions": {
        "seats": { "enabled": true, "defaultMax": 5 },
        "devices": { "enabled": true, "defaultMax": 3 },
        "expiry": { "enabled": true, "defaultDays": 365 },
        "features": { "enabled": true, "available": ["analytics", "export", "api-access"] },
        "keyFormat": {
          "prefix": "VIG",
          "segments": 4,
          "segmentLength": 4,
          "separator": "-",
          "charset": "BASE32"
        }
      },
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "pages": 1 }
}

POST/api/licensing/policiesRequires: manage:license-policies

Créer une nouvelle politique de licence.

Corps de la requête


{
  "name": "Pro Plan",
  "slug": "pro-plan",
  "validationMode": "HYBRID",
  "dimensions": {
    "seats": { "enabled": true, "defaultMax": 5 },
    "devices": { "enabled": true, "defaultMax": 3 },
    "expiry": { "enabled": true, "defaultDays": 365 },
    "features": { "enabled": true, "available": ["analytics", "export"] },
    "keyFormat": {
      "prefix": "VIG",
      "segments": 4,
      "segmentLength": 4,
      "separator": "-",
      "charset": "BASE32"
    }
  }
}

Champ	Type	Requis	Description
`name`	`string`	Oui	Nom d’affichage
`slug`	`string`	Oui	Slug unique (ex. `pro-plan`)
`validationMode`	`ONLINE \| HYBRID \| OFFLINE`	Non	Par défaut : `HYBRID`
`dimensions`	`object`	Non	Configuration des sièges, appareils, fonctionnalités, expiration et format de clé
`offlineGraceDays`	`number`	Non	Jours pendant lesquels une clé reste valide hors connexion (par défaut : 7)
`revocationTtlMin`	`number`	Non	Minutes avant la propagation de la révocation (par défaut : 60)

GET/api/licensing/policies/:idRequires: manage:license-policies

Obtenir une politique par son ID.

PATCH/api/licensing/policies/:idRequires: manage:license-policies

Mettre à jour une politique. Seuls les champs fournis sont modifiés.

DELETE/api/licensing/policies/:idRequires: manage:license-policies

Supprimer une politique. Échoue si des clés sont encore émises sous cette politique.

Clés

Les clés sont émises selon une politique et attribuées à un titulaire de licence (utilisateur, organisation ou appareil).

GET/api/licensing/keysRequires: manage:license-keys

Lister toutes les clés. Filtrable par statut et politique.

Paramètres de requête

Paramètre	Type	Description
`page`	`number`	Numéro de page
`limit`	`number`	Éléments par page
`policyId`	`string`	Filtrer par politique
`status`	`ACTIVE \| SUSPENDED \| REVOKED \| EXPIRED`	Filtrer par statut

POST/api/licensing/keysRequires: manage:license-keys

Émettre une nouvelle clé de licence.

Corps de la requête


{
  "policyId": "pol_abc123",
  "licenseeType": "USER",
  "licenseeId": "user_xyz789",
  "notes": "Issued via Stripe checkout"
}

La réponse inclut l’objet clé complet avec key (la chaîne de licence) et jwtToken (pour la validation hors connexion).

GET/api/licensing/keys/:idRequires: manage:license-keys

Obtenir une clé par son ID, incluant la politique, les sièges et les appareils associés.

POST/api/licensing/keys/:id/suspendRequires: manage:license-keys

Suspendre une clé. Elle peut être réactivée ultérieurement.

POST/api/licensing/keys/:id/revokeRequires: manage:license-keys

Révoquer définitivement une clé.

POST/api/licensing/keys/:id/reissueRequires: manage:license-keys

Réémettre une clé avec des droits mis à jour. L’ancienne clé est révoquée et une nouvelle est générée.

Corps optionnel


{
  "features": ["analytics", "export", "api-access"],
  "seatMax": 10,
  "deviceMax": 5,
  "expiresAt": "2027-03-15T00:00:00Z"
}

Sièges

GET/api/licensing/keys/:id/seatsRequires: manage:license-keys

Lister tous les sièges (utilisateurs assignés) pour une clé.

POST/api/licensing/keys/:id/seatsRequires: manage:license-keys

Assigner un siège à un utilisateur. Échoue si la limite de sièges est atteinte.


{ "userId": "user_abc" }

DELETE/api/licensing/keys/:id/seats/:userIdRequires: manage:license-keys

Libérer un siège d’un utilisateur.

Appareils

GET/api/licensing/keys/:id/devicesRequires: manage:license-keys

Lister tous les appareils activés pour une clé.

DELETE/api/licensing/keys/:id/devices/:deviceIdRequires: manage:license-keys

Supprimer un appareil d’une clé.

Validation (Publique)

Ces endpoints sont appelés par ton application à l’exécution. Aucun Bearer token n’est requis.

POST/api/licensing/validate

Valider une clé de licence en ligne. Retourne la validité, les fonctionnalités, le nombre de sièges/appareils et l’expiration.

Corps de la requête


{ "key": "VIG-A8BC-D3EF-G4HJ-K5LM" }

Réponse en cas de succès


{
  "valid": true,
  "features": ["analytics", "export"],
  "seats": { "used": 2, "max": 5 },
  "devices": { "used": 1, "max": 3 },
  "expiresAt": "2027-01-15T00:00:00Z"
}

Réponse pour une clé invalide


{
  "valid": false,
  "reason": "REVOKED"
}

Valeurs possibles de reason : INVALID, EXPIRED, REVOKED, SUSPENDED, SEAT_LIMIT, DEVICE_LIMIT.

Activation d’appareil (Publique)

POST/api/licensing/activate

Enregistrer un appareil avec une clé de licence. Utilise ceci au premier lancement d’une application de bureau ou mobile.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "fingerprint": "a1b2c3d4e5f6",
  "name": "John's MacBook Pro"
}

Retourne 200 en cas de succès. Retourne 409 si la limite d’appareils est atteinte.

POST/api/licensing/deactivate

Retirer un appareil d’une clé. Utilise lors de la déconnexion ou de la désinstallation.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "fingerprint": "a1b2c3d4e5f6"
}

Suivi d’utilisation (Public)

POST/api/licensing/usage

Enregistrer une métrique d’utilisation pour une clé. Utile pour les licences basées sur la consommation.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "metric": "api_calls",
  "amount": 1
}

GET/api/licensing/usage/:key

Obtenir les données d’utilisation actuelles d’une clé pour toutes les métriques.

Liste de révocation (Publique)

GET/api/licensing/revocation-list

Retourne un JWT signé contenant tous les JTI des clés révoquées. Utilisé par le SDK pour la vérification de révocation hors connexion.

La réponse est en application/jwt avec Cache-Control: public, max-age=3600. Le SDK récupère cette liste automatiquement.

Règles d’automatisation

Les règles d’automatisation connectent les événements de paiement (Stripe, PayPal) aux actions de licence (émettre, activer, suspendre, révoquer).

GET/api/licensing/automationRequires: manage:license-policies

Lister toutes les règles d’automatisation.

POST/api/licensing/automationRequires: manage:license-policies

Créer une nouvelle règle d’automatisation.


{
  "name": "Stripe checkout → issue key",
  "provider": "stripe",
  "triggerEvent": "checkout.session.completed",
  "action": "issue_key",
  "policyId": "pol_abc123",
  "isActive": true
}

Fournisseur	Événements déclencheurs
`stripe`	`checkout.session.completed`, `invoice.paid`, `payment_intent.succeeded`
`paypal`	`PAYMENT.CAPTURE.COMPLETED`
`manual`	`manual_trigger`

Action	Description
`issue_key`	Émettre une nouvelle clé sous la politique liée
`activate_key`	Activer une clé existante
`suspend_key`	Suspendre une clé
`revoke_key`	Révoquer une clé

GET/api/licensing/automation/:idRequires: manage:license-policies

Obtenir une règle d’automatisation.

PATCH/api/licensing/automation/:idRequires: manage:license-policies

Mettre à jour une règle d’automatisation.

DELETE/api/licensing/automation/:idRequires: manage:license-policies

Supprimer une règle d’automatisation.

Webhooks

Ces endpoints reçoivent les événements des fournisseurs de paiement. Ils sont vérifiés par signature et ne nécessitent pas de Bearer token.

POST/api/licensing/webhooks/stripe

Reçoit les événements webhook Stripe. Vérifié via l’en-tête stripe-signature. Configure STRIPE_LICENSING_WEBHOOK_SECRET dans ton environnement.

POST/api/licensing/webhooks/paypal

Reçoit les événements webhook PayPal. Vérifié via HMAC-SHA256. Configure PAYPAL_LICENSING_WEBHOOK_SECRET et PAYPAL_LICENSING_WEBHOOK_ID dans ton environnement.

Statistiques

GET/api/licensing/statsRequires: view:license-stats

Retourne les statistiques agrégées de licences.


{
  "success": true,
  "data": {
    "totalPolicies": 3,
    "totalKeys": 142,
    "activeKeys": 98,
    "revokedKeys": 12,
    "suspendedKeys": 5,
    "expiredKeys": 27,
    "policyDistribution": [
      { "policyId": "pol_abc", "policyName": "Pro Plan", "count": 80 }
    ],
    "recentKeys": []
  }
}