Authentification et clés d'API
Présenter la clé
Chaque appel porte la clé dans l'en-tête Authorization :
Authorization: Bearer fpk_9al41uPRzeglnYvHa3YfvsK86OfQwx6BmC2EKmI0Vhw
- Le mot
Bearerest insensible à la casse, les espaces autour du secret sont ignorés. - Pas d'appel de connexion, pas de session, pas de cookie, pas de signature. Un cookie de session du tableau de bord n'est jamais accepté sur
/v1.
| Situation | Réponse |
|---|---|
| En-tête absent ou vide | 401 API_KEY_MISSING, avec WWW-Authenticate: Bearer realm="freshperf-api" |
| Secret inconnu | 401 API_KEY_INVALID |
Clé passée en paramètre d'URL (?api_key=, ?apikey=, ?key=, ?token=, ?access_token=) | 400 API_KEY_IN_QUERY |
En-tête X-Acting-Account présent | 400 API_HEADER_NOT_ALLOWED |
Ce qu'est une clé
| La clé | Détail |
|---|---|
| Secret | fpk_ + 43 caractères, soit 47 en tout |
| Stockage | seule une empreinte est conservée. Le secret s'affiche une fois, à la création ou au renouvellement |
keyPrefix | les 12 premiers caractères (fpk_ + 8), affichés dans le tableau de bord, les journaux et les e-mails |
| Agit en tant que | le titulaire du compte, sur son propre compte |
| Plafond | 25 clés utilisables par compte (actives et non expirées) |
Une clé ne peut pas agir sur un compte que quelqu'un a partagé avec vous, et ne peut ni créer, ni lister, ni révoquer d'autres clés.
Le statut, l'expiration, la liste d'adresses et le compte propriétaire sont relus à chaque appel. Rien n'est mis en cache : une révocation ou une restriction resserrée s'applique dès l'appel suivant.
Cycle de vie
Tout se passe dans Compte > Clés d'API.
| Geste | Effet | Confirmation d'identité |
|---|---|---|
| Créer | choisit nom, permissions, restrictions, expiration, plafond. Le secret s'affiche une fois | oui |
| Affaiblir | moins de permissions, moins de services, plus de règles d'adresse, expiration avancée, plafond baissé | non |
| Élargir | l'inverse de la ligne précédente | oui |
| Renouveler | nouveau secret, mêmes réglages, ancien secret tué au même instant | oui |
| Révoquer | la clé meurt. Appels suivants : 403 API_KEY_REVOKED | non |
| Expirer | à la date choisie. Appels suivants : 403 API_KEY_EXPIRED | - |
Une clé peut vivre sans expiration ; le tableau de bord les signale. Supprimer le compte supprime toutes ses clés.
E-mails envoyés au titulaire : création, renouvellement, expiration dans 7 jours, révocation par un administrateur, et appel refusé hors liste d'adresses (au plus un par jour et par clé).
Confirmer que c'est bien vous
Créer, renouveler ou élargir une clé demande une preuve, la plus forte que le compte possède.
| Facteur | Condition | Refus possibles |
|---|---|---|
| Code de double authentification (ou code de secours) | 2FA activée | 400 TOTP_REQUIRED si absent, 403 INVALID_2FA_CODE si faux |
| Mot de passe | 2FA inactive, mot de passe défini | 403 CURRENT_PASSWORD_INCORRECT |
| Code à 6 chiffres envoyé par e-mail | compte sans mot de passe ni 2FA (connexion par Google ou équivalent) | 400 EMAIL_CODE_REQUIRED, 403 EMAIL_CODE_INVALID, 410 EMAIL_CODE_EXPIRED, 429 EMAIL_CODE_LOCKED après cinq essais |
Le code e-mail vaut 15 minutes. Cinq preuves fausses en quinze minutes, tous facteurs confondus, verrouillent l'étape : 429 STEP_UP_LOCKED.
Surveiller une clé
Le tableau de bord conserve, par clé :
| Trace | Rétention | Contenu |
|---|---|---|
| Journal des requêtes | 30 jours | route, statut HTTP, adresse appelante, durée, X-Request-Id, et la raison des refus |
| Historique des événements | 1 an | création, modification, renouvellement, révocation, expiration, et par qui |
La route journalisée est le gabarit (/v1/services/{code}/power), jamais le chemin concret ni la chaîne de requête.
Un appel dont le porteur ne correspond à aucune clé n'est pas journalisé. Une rafale de 403 API_KEY_IP_NOT_ALLOWED dans le journal signale un secret utilisé ailleurs que là où vous l'avez installé.