Passer au contenu principal

Token Bearer

Chaque requête doit inclure le header :
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

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 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 : 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.
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.
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.
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, puis contactez Avest pour le changer.

Connaître le type de votre clé

GET Key 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.

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

Ne faites jamais de correspondance exacte sur message : basez-vous sur le code HTTP. Le texte est destiné au diagnostic et peut évoluer.
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.