Authentification par clé API

Format de la clé

La clé est composée d'un identifiant public (keyId) et d'un secret. Seul le secret est haché en base de données — le keyId est stocké en clair pour permettre la recherche.

• Formemk_live_<keyId>.<secret>
• keyId22 caractères base64url. Visible dans le tableau de bord (les 4 derniers caractères du secret servent à identifier la clé).
• secret43 caractères base64url. Affiché une seule fois à la création — perdu, il n'est pas récupérable. Créez une nouvelle clé et révoquez l'ancienne.

curl https://api.mastro.app/v1/quotes \
  -H "Authorization: Bearer mk_live_<keyId>.<secret>"

Cycle de vie

La gestion des clés se fait depuis l'onglet Développeurs de l'application Mastro.

• Création : un nom, c'est tout. Le secret apparaît dans une fenêtre — copiez-le immédiatement.
• Rotation : créez une nouvelle clé, déployez-la, puis révoquez l'ancienne. Pas de rotation in-place — c'est volontaire.
• Révocation : effet immédiat, irréversible. Une clé révoquée renvoie 401 sur toutes les requêtes suivantes.

Limites de débit

Chaque clé est soumise à une fenêtre de 1 minute selon le plan d'abonnement de son propriétaire.

Une limite supplémentaire de 30 requêtes/minute par adresse IP s'applique avant l'authentification (anti-bruteforce sur les keyId inconnus).

Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. En cas de dépassement, attendez la valeur de Retry-After (en secondes).

Bonnes pratiques

• Stockez la clé dans un secret manager (1Password, AWS Secrets Manager, Vault). Jamais dans le code source.
• Une clé par environnement (prod vs staging). En cas de fuite, vous limitez le rayon d'impact.
• Surveillez les logs d'accès dans le tableau de bord — un usage anormal déclenche une alerte automatique.
• Pas de partage entre utilisateurs : chaque clé est liée à un compte Mastro et à ses ressources.