{"openapi":"3.1.0","info":{"title":"Xenora License Cloud API","version":"1.1.0","description":"Validation, activation et gestion de licences logicielles. Toutes les réponses suivent l'enveloppe { success, data | error, request_id }. Chaque clé API a des permissions (portées) ; les opérations de création et de révocation exigent une clé secrète et une requête signée. Guide et exemples : documentation Xenora, page License Cloud."},"servers":[{"url":"https://api.xenora.bid/v1"}],"security":[{"bearer":[]}],"paths":{"/licenses/validate":{"post":{"summary":"Valider une licence","description":"Clé publique ou secrète. Répond toujours 200 : lisez data.valid et data.code.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["license_key"],"properties":{"license_key":{"type":"string","example":"LC-7K2M-9QXA-R4TD-8HNV"},"device_id":{"type":"string","maxLength":200,"description":"Identifiant stable et unique de la machine (haché côté serveur)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Résultat","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"valid":{"type":"boolean"},"code":{"enum":["VALID","NOT_FOUND","SUSPENDED","REVOKED","EXPIRED","SUBSCRIPTION_INACTIVE","DEVICE_NOT_ACTIVATED"]},"license":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"enum":["ACTIVE","SUSPENDED","REVOKED"]},"kind":{"enum":["standard","trial"]},"expires_at":{"type":["string","null"],"format":"date-time"},"remaining_seconds":{"type":["integer","null"]},"duration_days":{"type":["integer","null"]},"activated_at":{"type":["string","null"],"format":"date-time"},"max_devices":{"type":["integer","null"]},"activations":{"type":"integer"},"label":{"type":["string","null"]}}},{"type":"null"}]}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Opération refusée (SECRET_KEY_REQUIRED, SCOPE_MISSING, SIGNING_SECRET_MISSING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, LICENSE_SUBSCRIPTION_INACTIVE, PLAN_LIMIT_*)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/licenses/heartbeat":{"post":{"summary":"Battement de cœur d'un appareil activé","description":"Portée licenses:heartbeat. À appeler au démarrage puis toutes les next_heartbeat_in secondes. Un même appareil vu depuis deux adresses en moins de 2 minutes signale la licence (usage simultané).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["license_key","device_id"],"properties":{"license_key":{"type":"string","example":"LC-7K2M-9QXA-R4TD-8HNV"},"device_id":{"type":"string","maxLength":200,"description":"Identifiant stable et unique de la machine (haché côté serveur)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Résultat","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"valid":{"type":"boolean"},"code":{"enum":["VALID","NOT_FOUND","SUSPENDED","REVOKED","EXPIRED","SUBSCRIPTION_INACTIVE","DEVICE_NOT_ACTIVATED"]},"license":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"enum":["ACTIVE","SUSPENDED","REVOKED"]},"kind":{"enum":["standard","trial"]},"expires_at":{"type":["string","null"],"format":"date-time"},"remaining_seconds":{"type":["integer","null"]},"duration_days":{"type":["integer","null"]},"activated_at":{"type":["string","null"],"format":"date-time"},"max_devices":{"type":["integer","null"]},"activations":{"type":"integer"},"label":{"type":["string","null"]}}},"next_heartbeat_in":{"type":"integer"}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Opération refusée (SECRET_KEY_REQUIRED, SCOPE_MISSING, SIGNING_SECRET_MISSING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, LICENSE_SUBSCRIPTION_INACTIVE, PLAN_LIMIT_*)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/licenses/status":{"get":{"summary":"État d'une licence","description":"Portée licenses:status.","parameters":[{"name":"X-License-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Clé de licence (jamais dans l'URL)."}],"responses":{"200":{"description":"État","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"valid":{"type":"boolean"},"code":{"enum":["VALID","NOT_FOUND","SUSPENDED","REVOKED","EXPIRED","SUBSCRIPTION_INACTIVE","DEVICE_NOT_ACTIVATED"]},"license":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"enum":["ACTIVE","SUSPENDED","REVOKED"]},"kind":{"enum":["standard","trial"]},"expires_at":{"type":["string","null"],"format":"date-time"},"remaining_seconds":{"type":["integer","null"]},"duration_days":{"type":["integer","null"]},"activated_at":{"type":["string","null"],"format":"date-time"},"max_devices":{"type":["integer","null"]},"activations":{"type":"integer"},"label":{"type":["string","null"]}}}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Opération refusée (SECRET_KEY_REQUIRED, SCOPE_MISSING, SIGNING_SECRET_MISSING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, LICENSE_SUBSCRIPTION_INACTIVE, PLAN_LIMIT_*)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Licence introuvable dans ce projet (LICENSE_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/licenses/devices":{"get":{"summary":"Appareils activés","description":"Portée devices:read. Aucune adresse IP n'est renvoyée.","parameters":[{"name":"X-License-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Clé de licence (jamais dans l'URL)."}],"responses":{"200":{"description":"Appareils","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"devices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"device_name":{"type":["string","null"]},"activated_at":{"type":"string"},"last_seen_at":{"type":"string"}}}}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Opération refusée (SECRET_KEY_REQUIRED, SCOPE_MISSING, SIGNING_SECRET_MISSING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, LICENSE_SUBSCRIPTION_INACTIVE, PLAN_LIMIT_*)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Licence introuvable dans ce projet (LICENSE_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/licenses/devices/{deviceId}":{"delete":{"summary":"Retirer un appareil","description":"Portée devices:delete. deviceId = identifiant renvoyé par GET devices, ou identifiant d'installation.","parameters":[{"name":"X-License-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Clé de licence (jamais dans l'URL)."},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retiré","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"removed":{"const":true},"activations":{"type":"integer"}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Opération refusée (SECRET_KEY_REQUIRED, SCOPE_MISSING, SIGNING_SECRET_MISSING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, LICENSE_SUBSCRIPTION_INACTIVE, PLAN_LIMIT_*)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Licence introuvable dans ce projet (LICENSE_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/licenses/activate":{"post":{"summary":"Activer une licence sur un appareil","description":"Idempotent pour un même device_id. La limite d'appareils est garantie même sous requêtes simultanées.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["license_key","device_id"],"properties":{"license_key":{"type":"string","example":"LC-7K2M-9QXA-R4TD-8HNV"},"device_id":{"type":"string","maxLength":200,"description":"Identifiant stable et unique de la machine (haché côté serveur)."},"device_name":{"type":"string","maxLength":100}},"additionalProperties":false}}}},"responses":{"200":{"description":"Activé","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"activated":{"const":true},"already_activated":{"type":"boolean"},"activations":{"type":"integer"},"max_devices":{"type":["integer","null"]}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Opération refusée (SECRET_KEY_REQUIRED, SCOPE_MISSING, SIGNING_SECRET_MISSING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, LICENSE_SUBSCRIPTION_INACTIVE, PLAN_LIMIT_*)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Licence introuvable dans ce projet (LICENSE_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Limite d'appareils atteinte (DEVICE_LIMIT_REACHED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/licenses/deactivate":{"post":{"summary":"Libérer un appareil","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["license_key","device_id"],"properties":{"license_key":{"type":"string","example":"LC-7K2M-9QXA-R4TD-8HNV"},"device_id":{"type":"string","maxLength":200,"description":"Identifiant stable et unique de la machine (haché côté serveur)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Résultat","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"deactivated":{"type":"boolean"},"activations":{"type":"integer"}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Licence introuvable dans ce projet (LICENSE_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/licenses":{"post":{"summary":"Créer une licence (clé secrète, requête signée)","description":"La clé de licence n'est renvoyée qu'une seule fois. Requête sensible : clé secrète ET signature obligatoires. En-têtes X-Xenora-Timestamp (secondes Unix, ±5 min), X-Xenora-Nonce (16 à 64 caractères, usage unique) et X-Xenora-Signature = HMAC-SHA256 hexadécimal, avec le secret de signature de la clé, de « timestamp\nnonce\nMÉTHODE\nchemin\nSHA-256 hexadécimal du corps ». Erreurs 401 : SIGNATURE_REQUIRED, SIGNATURE_EXPIRED, INVALID_SIGNATURE, REPLAY_DETECTED.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"key":{"type":"string","minLength":8,"maxLength":64,"description":"Clé personnalisée (sinon générée)"},"kind":{"enum":["standard","trial"]},"duration_days":{"type":["integer","null"],"minimum":1,"description":"Durée qui démarre à la première activation"},"label":{"type":"string","maxLength":100},"customer_email":{"type":"string","format":"email"},"max_devices":{"type":["integer","null"],"minimum":1},"expires_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false}}}},"responses":{"201":{"description":"Créée","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"license":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string","example":"LC-7K2M-9QXA-R4TD-8HNV"},"status":{"const":"ACTIVE"},"label":{"type":["string","null"]},"customer_email":{"type":["string","null"]},"max_devices":{"type":["integer","null"]},"expires_at":{"type":["string","null"]},"created_at":{"type":"string"}}}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Opération refusée (SECRET_KEY_REQUIRED, SCOPE_MISSING, SIGNING_SECRET_MISSING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, LICENSE_SUBSCRIPTION_INACTIVE, PLAN_LIMIT_*)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/licenses/revoke":{"post":{"summary":"Révoquer une licence (clé secrète, requête signée)","description":"Définitif. Indiquez id ou license_key. Requête sensible : clé secrète ET signature obligatoires. En-têtes X-Xenora-Timestamp (secondes Unix, ±5 min), X-Xenora-Nonce (16 à 64 caractères, usage unique) et X-Xenora-Signature = HMAC-SHA256 hexadécimal, avec le secret de signature de la clé, de « timestamp\nnonce\nMÉTHODE\nchemin\nSHA-256 hexadécimal du corps ». Erreurs 401 : SIGNATURE_REQUIRED, SIGNATURE_EXPIRED, INVALID_SIGNATURE, REPLAY_DETECTED.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"id":{"type":"string","format":"uuid"},"license_key":{"type":"string","example":"LC-7K2M-9QXA-R4TD-8HNV"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Révoquée","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"const":true},"data":{"type":"object","properties":{"revoked":{"const":true},"id":{"type":"string"}}},"request_id":{"type":"string"}}}}}},"400":{"description":"Requête invalide (VALIDATION_ERROR, INVALID_JSON)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Clé API absente, invalide ou révoquée (INVALID_API_KEY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Opération refusée (SECRET_KEY_REQUIRED, SCOPE_MISSING, SIGNING_SECRET_MISSING, LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_EXPIRED, LICENSE_SUBSCRIPTION_INACTIVE, PLAN_LIMIT_*)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Licence introuvable dans ce projet (LICENSE_NOT_FOUND)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite par minute de la formule (RATE_LIMITED) ou de l'application (APP_RATE_LIMITED), en-tête Retry-After ; quota mensuel atteint (QUOTA_EXCEEDED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"nx_pk_live_… (publique) ou nx_sk_live_… (secrète)"}},"schemas":{"Error":{"type":"object","required":["success","error","request_id"],"properties":{"success":{"const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"request_id":{"type":"string"}}}}}}