> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avest.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentification

> Comment authentifier vos requêtes à l'API d'intégration externe Avest.

## Token Bearer

Chaque requête doit inclure le header :

```
Authorization: Bearer {token}
```

Le token est une clé API rattachée à un **groupe d'agences**. Il donne accès aux données des agences de ce groupe que la clé couvre, et uniquement de celles-ci.

## Périmètre d'accès

> [!NOTE]
>
> La clé doit être rattachée à un groupe d'agences. Une requête effectuée avec
> une clé sans groupe d'agences est refusée avec `400 LinkedAPI agencyGroup is
>     required`.

* Le token est limité aux opérations d'intégration externe (création, mise à jour, lecture, recherche).
* Les données accessibles sont automatiquement restreintes au groupe d'agences de la clé.
* Une agence ouverte dans ce groupe après la création de la clé entre d'elle-même dans son périmètre. [GET Agencies](https://developers.avest.fr/endpoints/get-agencies.md) liste les agences que votre clé couvre.

## Types de clé

Chaque clé a un **type** fixé par Avest, indépendant du groupe d'agences. Le type décide des méthodes HTTP autorisées :

| Type | `access` (via [GET Key](https://developers.avest.fr/endpoints/get-key.md)) | Méthodes autorisées | Attribution |
| - | - | - | - |
| **Lecture seule** | `readOnly` | `GET` | Sur demande |
| **Lecture-écriture** | `readWrite` | `GET`, `POST`, `PATCH` | Par défaut |
| **Lecture-écriture + suppression** | `readWriteDelete` | `GET`, `POST`, `PATCH`, `DELETE` | Sur demande, au cas par cas |

Chaque page de route indique la **clé requise**. Une méthode non autorisée par votre clé est refusée avec `403 Not authorized to access this resource`.

> [!WARNING]
>
> **La clé avec suppression est dangereuse.** Un `DELETE` est définitif : aucune
> corbeille, aucune restauration possible depuis l'API ou l'interface Avest. Une boucle
> mal écrite, un mauvais identifiant ou un token qui fuite peut effacer des données
> de vos agences sans retour possible. Ne la demandez que si votre intégration doit
> vraiment supprimer. Gardez son token côté serveur, jamais dans une application
> cliente, et utilisez une clé en lecture seule ou en lecture-écriture partout où la
> suppression n'est pas nécessaire.

> [!WARNING]
>
> **Responsabilité.** Une suppression faite avec votre clé est une action de votre
> intégration, et elle relève de **votre responsabilité**. Avest ne s'engage ni à
> l'annuler ni à restaurer les données supprimées, et ne saurait en être tenu responsable.
> Si Avest accepte de restaurer des données supprimées via l'API, cette restauration
> pourra être **facturée**. Chaque appel à l'API est journalisé avec la clé qui l'a émis
> (clé, route, identifiant visé, date, résultat). Demander la clé avec suppression vaut
> acceptation de ces conditions.

> [!WARNING]
>
> Ce `403` est **strictement identique** à celui d'une requête sans header
> `Authorization` : même code, même `message`. Si vos `GET` passent mais qu'une
> écriture renvoie `403`, votre clé n'autorise pas cette méthode. Vérifiez son
> type avec [GET Key](https://developers.avest.fr/endpoints/get-key.md), puis contactez Avest pour le changer.

### Connaître le type de votre clé

[GET Key](https://developers.avest.fr/endpoints/get-key.md) renvoie le type de la clé utilisée et la liste exacte des méthodes qu'elle autorise. La route répond à toute clé, lecture seule comprise.

```bash theme={null}
curl "https://api.avest.fr/v1/external-integration/key" \
  -H "Authorization: Bearer {token}"
```

## Clés sécurisées (restriction d'IP)

Certaines clés sont configurées en mode **sécurisé** : la requête doit alors provenir d'une IP autorisée, transmise via le header `X-Real-IP`. Une requête provenant d'une autre IP est refusée avec `403 Not authorized to access this resource`.

## Limites de débit

Deux limites s'appliquent ; la première atteinte déclenche un `429` :

* **Par route** : chaque page d'endpoint indique son débit par minute. Le
  compteur est **commun à toutes les clés de votre groupe d'agences** : deux
  intégrations du même groupe partagent le même budget. Il est tenu **par
  chemin exact** : `PATCH /external-integration/contact/{contactId}` compte à
  part pour chaque contact ; les paramètres de query ne comptent pas.
* **Globale** : **200 requêtes par tranche de 10 secondes et par clé**, toutes
  routes confondues. Au-delà, la réponse est `429` avec
  `"message": "Too many requests, please try again later"`.

Dans les deux cas, la réponse porte `Retry-After` (secondes) et `retryAfter`
dans le corps. Étalez les synchronisations en masse plutôt que de les lancer en
parallèle.

## Réponses d'erreur d'authentification

| Code | `message` | Cause |
| - | - | - |
| `403` | `Not authorized to access this resource` | Header `Authorization` absent ; méthode non autorisée par le type de la clé (écriture avec une clé en lecture seule, `DELETE` sans l'option suppression) ; IP non autorisée sur une clé sécurisée. |
| `401` | `Invalid bearer token` | Token malformé, signature invalide, ou header `Authorization: Bearer` sans valeur. |
| `401` | `Not authorized to access this resource` | Token bien formé mais ne correspondant à aucune clé (clé révoquée ou régénérée). |
| `400` | `Not authorized to access this resource` | Clé désactivée. |
| `400` | `LinkedAPI agencyGroup is required` | Clé sans groupe d'agences rattaché. |

> [!NOTE]
>
> **Ne faites jamais de correspondance exacte sur `message`** : basez-vous sur le
> code HTTP. Le texte est destiné au diagnostic et peut évoluer.

> [!WARNING]
>
> Votre token est un secret. Ne le partagez jamais publiquement (dépôt Git,
> front-end, logs). En cas de fuite, contactez Avest pour le régénérer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.