> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.fidly.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentification

> OAuth2 client credentials, durée de vie de l'access_token, rotation du refresh_token et droits.

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 :

<CodeGroup>
  ```bash Client credentials theme={null}
  curl -X POST https://api.fidly.be/auth/token \
    -H "Content-Type: application/json" \
    -d '{
      "grant_type": "client_credentials",
      "client_id": "VOTRE_CLIENT_ID",
      "client_secret": "VOTRE_CLIENT_SECRET"
    }'
  ```

  ```bash Refresh token theme={null}
  curl -X POST https://api.fidly.be/auth/token \
    -H "Content-Type: application/json" \
    -d '{
      "grant_type": "refresh_token",
      "refresh_token": "VOTRE_REFRESH_TOKEN"
    }'
  ```
</CodeGroup>

Les deux renvoient la même forme :

```json theme={null}
{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "b3f1..."
}
```

## 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.

| Situation                                  | Réponse                        |
| ------------------------------------------ | ------------------------------ |
| `access_token` absent ou invalide          | `401 invalid_token`            |
| `access_token` valide sans le droit requis | `403 insufficient_permissions` |

## 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.

<Warning>
  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`.
</Warning>