Utilisation de l'API — Headers & Rate Limits

Ce chapitre couvre les headers HTTP, les règles CORS et le throttling. Lisez Conventions REST d'abord.

---

Headers requis

Appels frontend (Bearer + enriched)

httpCopier
Authorization: Bearer <keycloak_access_token>
x-enriched-token: <wakastart_token>
Content-Type: application/json

Appels backend (API Key)

httpCopier
x-api-key: sk_live_...
Content-Type: application/json

---

Headers optionnels

Pas de x-trace-id/x-request-id : ces headers ne sont pas implémentés à ce jour (aucune occurrence côté public-api, backend-for-front ou discovery). Pour un incident support, fournir l'horodatage, la route appelée et le corps de la réponse d'erreur.

---

CORS

L'API WakaStart supporte CORS pour les origines enregistrées. Les règles :

• Origines autorisées : configurées dans ALLOWED_ORIGINS côté API.
• Credentials : Access-Control-Allow-Credentials: true — les cookies HttpOnly sont transmis.
• Méthodes : GET, POST, PUT, PATCH, DELETE, OPTIONS.
• Headers exposés : Retry-After.

Appels directs depuis le browser : si votre frontend appelle l'API sans proxy, le cookie wakastart_token est HttpOnly et inaccessible depuis JavaScript. Vous ne pouvez pas passer x-enriched-token côté browser sans proxy. Utilisez toujours un proxy serveur.

---

Idempotence

Les opérations GET, PUT et DELETE sont idempotentes. Pour POST :

• Création d'invitation : si une invitation PENDING existe déjà pour le même email + Customer, l'API répond 409 Conflict. C'est sûr de retenter après un échec réseau.
• Enrichissement : /api/auth/enrich est idempotent pour un même access_token dans sa période de validité.
• Token refresh : /api/auth/token/refresh génère un nouveau token à chaque appel. Ne pas appeler en parallèle.

---

Rate limiting

L'API applique trois niveaux de throttling :

Limites spécifiques par endpoint

Réponse 429 :

jsonCopier
{ "statusCode": 429, "message": "Too Many Requests" }

Le header Retry-After indique la durée d'attente en secondes.

---

Backoff exponentiel

typescriptCopier
async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 3
): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "1", 10);
    const delay = retryAfter * 1000 * Math.pow(2, attempt);
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error("Rate limit exceeded after retries");
}

---

Vérification de droits depuis votre backend

httpCopier
POST /api/token/authorize
x-api-key: sk_live_...
Content-Type: application/json

{
  "token": "eyJ...",
  "checks": {
    "adminLevel": { "requiredLevel": "CustomerAdmin" },
    "roles": { "roles": ["CONFIG"], "mode": "any" },
    "appRights": { "rights": ["users.create"], "mode": "all" }
  }
}

jsonCopier
{
  "authorized": true,
  "details": {
    "adminLevel": { "hasLevel": true,  "actualLevel": "NetworkAdmin" },
    "roles":      { "hasRoles": true,  "matchedRoles": ["CONFIG"] },
    "appRights":  { "hasRights": true, "missingRights": [] }
  }
}

---

Bonnes pratiques

• Headers ne se cumulent pas : un appel avec x-api-key ET Authorization: Bearer verra la clé API prévaloir.
• Logger le corps de la réponse d'erreur sur les 5xx (route, méthode, statusCode, message) : à défaut de x-request-id, c'est ce qui permet au support de retrouver l'incident.
• Respecter Retry-After : ne pas ignorer ce header, il protège la stabilité de l'API.

Pièges classiques

• Appels parallèles au refresh : si plusieurs requêtes expirent en même temps et tentent toutes un refresh simultané, une seule réussit. Implémenter un mutex côté client.
• Rate limit sur les tests : en CI, une batterie de tests peut déclencher le rate limit de courte durée. Ajouter des délais entre les tests d'intégration.

Aller plus loin

• Erreurs HTTP : codes 429 et 401 détaillés
• Bonnes pratiques sécurité : tokens, secrets, HTTPS