maestor / docs

Authentification

Bearer Token, anti-replay timestamp, gestion des erreurs 401/403.

L’API Maestor utilise une authentification par clé API (Bearer Token) avec protection anti-rejeu sur les opérations d’écriture.

Header Authorization

Toutes les requêtes doivent inclure :

Authorization: Bearer sk_votre_cle_api

Sans header valide, l’API renvoie :

HTTP/1.1 401 Unauthorized
{ "success": false, "error": "Missing or invalid API key" }

Anti-rejeu (X-Request-Timestamp)

Pour les opérations POST, PUT, DELETE, un en-tête X-Request-Timestamp est requis :

POST /api/v1/sav HTTP/1.1
Authorization: Bearer sk_votre_cle_api
X-Request-Timestamp: 1706800000
Content-Type: application/json
  • Le timestamp doit être un Unix timestamp en secondes (UTC)
  • Fenêtre acceptée : ±5 minutes par rapport à l’heure serveur
  • En dehors de cette fenêtre : 401 Unauthorized avec { "error": "Replay attack suspected" }

Synchronisation NTP : Synchronisez votre serveur sur NTP (ntp.infomaniak.com par exemple) pour éviter les drifts d’horloge qui rejetteraient vos appels.

Permissions refusées (403)

Si la clé API n’a pas la permission requise pour l’endpoint :

HTTP/1.1 403 Forbidden
{ "success": false, "error": "Permission denied", "required": "sav:write" }

Solution : régénérer la clé avec la permission manquante depuis Paramètres → API.

Bonnes pratiques

  • Une clé par intégration — pas de partage
  • Whitelist IP activée si possible
  • Rotation annuelle (set expiration to 1 an)
  • Logging : Maestor logge chaque appel API avec horodatage + IP + endpoint pour audit