L’API utilise le flux OAuth2 client credentials. Chaque intégration possède une
paire client_id / client_secret, émise et gérée dans l’interface Fidly.
Récupérer les clés
POST /auth/token accepte un corps JSON et deux grant types :
Les deux renvoient la même forme :
Access token
L’access_token est un JWT valable 1 heure (expires_in: 3600), à envoyer
sur chaque requête dans l’en-tête Authorization: Bearer <access_token>.
Les droits du client y sont embarqués à l’émission : un droit accordé ou révoqué
dans l’interface prend effet au prochain access_token, pas sur ceux déjà
émis.
Refresh token
Le refresh_token permet d’obtenir une nouvelle paire de clés sans renvoyer le
client_secret. Sa durée de validité est illimitée tant qu’il n’est pas
consommé. Il est à usage unique : le consommer invalide celui envoyé et
renvoie une nouvelle paire access_token + refresh_token — le refresh_token
reçu est neuf, sa validité repart de zéro.
Chaque client_id n’a droit qu’à un refresh_token actif à la fois. Si plusieurs
processus partagent un client_id, faites-leur partager les clés — chacun
demandant les siennes déconnecterait les autres. Mettez donc l’access_token en
cache et réutilisez-le pendant son heure de validité, plutôt que d’en redemander
un à chaque appel.
Droits
Les droits de votre client se règlent avec une granularité par action et par
ressource : pour chaque ressource (document, relation, bank_account,
journal, branding), chaque action — créer, lire, modifier, supprimer —
s’autorise ou non depuis l’interface Fidly. Les quatre actions sont toujours
paramétrables ; une action sans route correspondante aujourd’hui est simplement
sans effet.
Les listes de référence (/units-of-measure, /currencies, /countries) exigent
un access_token valide mais aucun droit de ressource.
Sécurité
Quelques choix de gestion des clés, à connaître pour intégrer sereinement :
Blocage temporaire sur les échecs. Des authentifications échouées répétées sur
un même client_id déclenchent un 429 too_many_requests temporaire, pour
ralentir le bruteforce. Attendez avant de réessayer ; une authentification réussie remet le
compteur à zéro.
Une seule paire active par client. Recréer une paire via les client
credentials écrase le refresh_token précédent : toute session de rafraîchissement
antérieure est invalidée. Un access_token déjà émis reste en revanche valable
jusqu’à son expiration — la révocation d’un droit prend donc effet au plus tard une
heure après.
La rotation révèle un vol. Un refresh_token déjà utilisé échoue en
401 invalid_grant. Si cela se produit sans explication de votre côté, considérez
la paire comme compromise et repartez de vos client credentials.
Rien de sensible en clair. Côté Fidly, le client_secret et le
refresh_token sont stockés hashés : une fuite ne donnerait aucune clé
réutilisable.
Nous vous conseillons de conserver vos clés pour les réutiliser pendant leur durée
de validité — en mémoire ou en base de données, selon votre architecture — sans
jamais logger un token complet ni le client_secret.
