Documentation développeur

Authentification

Tous les endpoints authentifiés attendent un token Bearer dans le header Authorization. Générez vos clés sur /account/api-keys.

curl https://xen-support.com/api/v1/me \
  -H "Authorization: Bearer xs_live_a1b2c3d4e5f6..."

Format clé : xs_live_ + 32 caractères hex. La clé n'est affichée qu'une seule fois à la création — seul son hash SHA-256 est conservé en base.

Rate limiting

60 requêtes par minute par clé (fenêtre glissante). En cas de dépassement :

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 60

{"error": {"code": "rate_limited", "message": "Rate limit exceeded (60/min)."}}

GET /api/v1/me

Scope : me:read

{
  "data": {
    "id": 42,
    "email": "user@example.com",
    "name": "John Doe",
    "username": "john-doe",
    "created_at": "2026-01-15 10:32:11"
  }
}

GET /api/v1/extensions

Public — pas d'auth requise. Retourne les extensions publiées.

curl https://xen-support.com/api/v1/extensions

GET /api/v1/licenses

Scope : licenses:read — Liste vos licences.

GET /api/v1/licenses/{key}

Vérification publique d'une licence par clé (sans auth). Retourne le statut de validité.

{
  "data": {
    "valid": true,
    "revoked": false,
    "expired": false,
    "domain": "forum.example.com",
    "expires_at": "2027-01-15 10:32:11",
    "extension": {
      "name": "Teams",
      "slug": "extension",
      "version": "1.0.0"
    }
  }
}

POST /api/v1/licenses/{key}/heartbeat

Scope : licenses:verify — Ping périodique depuis votre forum. Met à jour last_verified_at + verify_count. Body (optionnel) :

POST https://xen-support.com/api/v1/licenses/XS-ABC-DEF-GHI/heartbeat
Authorization: Bearer xs_live_...
Content-Type: application/json

{"domain": "forum.example.com"}

GET /api/v1/orders

Scope : orders:read — Retourne les 100 dernières commandes de votre compte.

Webhooks

Configurez vos webhooks sur /account/webhooks. Chaque POST est signé HMAC-SHA256 dans le header X-Webhook-Signature.

Événements disponibles :

• license.activated
• license.revoked
• license.domain_changed
• order.paid
• order.refunded
• subscription.created
• subscription.canceled

Vérifier la signature en PHP :

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $payload, 'whsec_VOTRE_SECRET');
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}
$event = json_decode($payload, true);
// process $event...

Gestion des erreurs

Toutes les erreurs renvoient un objet JSON :

{
  "error": {
    "code": "license_not_found",
    "message": "License key not found."
  }
}

Codes communs : missing_authorization · invalid_token · insufficient_scope · rate_limited · license_not_found · domain_mismatch