Authentification

Chaque requête à l'API ExoConnect doit porter une clé API dans l'en-tête HTTP x-api-key. C'est le seul mécanisme d'authentification : pas d'OAuth, pas de JWT, pas de session. Une clé n'est jamais retenue d'un appel à l'autre : chaque requête présente la sienne.

Obtenir une clé

Ouvrir ExoConnect

Lancez l'application ExoConnect sur le poste où l'API est installée.

Ouvrir le menu Clés d'API

La liste affiche vos clés, leur portée, leur date d'expiration et leur dernière utilisation.

Créer une clé

Créez une clé par application. Choisissez sa portée (lecture seule ou écriture) et, idéalement, une date d'expiration.

Gestion des clés d'API dans ExoConnect

Utiliser la clé

Ajoutez l'en-tête à chaque requête, sans préfixe (Bearer ou autre) :

x-api-key: VOTRE_CLE_API

cURL

Python

JavaScript

Gardez la clé dans une variable d'environnement (EXOCONNECT_API_KEY) ou un coffre de secrets, jamais dans le code source. Excluez l'en-tête x-api-key de vos journaux.

Ce qu'une clé permet

Deux contrôles s'additionnent avant toute lecture ou écriture dans Acomba.

1. La portée de la clé

Portée	Autorise	Sans elle
Lecture	Toutes les requêtes `GET`	—
Écriture	`POST`, `PUT`, `PATCH`, `DELETE`	`403` « Cette clé API ne permet pas l'écriture », avant tout dialogue avec Acomba
Données de paie sensibles (`payroll:sensitive`)	Voir le NAS, les coordonnées bancaires et les cumulatifs des employés ; créer un employé avec son NAS	Ces champs sont masqués dans les réponses. Une clé à qui cette portée a été explicitement refusée ne peut pas créer d'employé avec son NAS (`403` `scope_required`)

Une clé peut aussi avoir une date d'expiration. Après cette date, elle est refusée (403). Une clé révoquée dans ExoConnect est refusée dans les 30 secondes.

2. Les droits de l'utilisateur Acomba

ExoConnect se connecte à Acomba avec un utilisateur Acomba que vous choisissez. L'API ne peut jamais dépasser les droits de cet utilisateur : si l'utilisateur n'a pas accès à un module ou à une opération dans Acomba, aucune clé, même en écriture, ne pourra le faire.

Bonne pratique

Configurez ExoConnect avec un utilisateur Acomba dédié, limité à ce dont vos intégrations ont besoin. Une clé compromise reste alors contenue dans ce périmètre.

Erreurs d'authentification

Code	Corps de la réponse	Cause	Que faire
`401`	`{"detail": "Clé API manquante"}`	En-tête `x-api-key` absent ou vide	Ajoutez l'en-tête à chaque requête
`403`	`{"detail": "Clé API invalide"}`	Clé inconnue ou révoquée, faute de frappe, espace ou retour de ligne dans la valeur	Vérifiez la valeur ; créez une nouvelle clé au besoin
`403`	`{"detail": "Clé API expirée"}`	Date d'expiration dépassée	Créez une nouvelle clé
`403`	`{"detail": "Cette clé API ne permet pas l'écriture"}`	Écriture avec une clé en lecture seule	Utilisez une clé en écriture
`403`	`{"detail": "Licence absente ou inactive"}`	La licence ExoConnect n'est pas active	Contactez le soutien

Le nom de l'en-tête n'est pas sensible à la casse (X-Api-Key fonctionne), mais la valeur de la clé l'est.

Plusieurs dossiers Acomba

L'API sert un seul dossier (entreprise) Acomba à la fois : le dossier actif choisi dans ExoConnect. Vous n'avez aucun en-tête à ajouter. Si une requête vise un autre dossier que le dossier actif, elle répond 409 (« Organisation demandée non active ») : changez le dossier actif dans ExoConnect.

Bonnes pratiques

Une clé par application. Si un système est compromis, vous révoquez sa clé sans toucher aux autres.

Lecture seule par défaut. Ne donnez l'écriture qu'aux applications qui créent ou modifient des fiches.

Expiration et rotation. Donnez une date d'expiration aux clés des traitements automatisés et changez-les au moins une fois par an, ou dès qu'une personne qui les connaissait quitte l'organisation.

Audit. Passez en revue les clés actives et leur dernière utilisation dans ExoConnect.

Données de paie. Réservez la portée payroll:sensitive aux seules applications qui doivent traiter le NAS ou les coordonnées bancaires.

Pour l'architecture complète (tunnel chiffré, aucun port entrant, chiffrement au repos), voir la page Sécurité.

Obtenir une clé#

Utiliser la clé#

Ce qu'une clé permet#

1. La portée de la clé#

2. Les droits de l'utilisateur Acomba#

Erreurs d'authentification#

Plusieurs dossiers Acomba#

Bonnes pratiques#

Obtenir une clé

Utiliser la clé

Ce qu'une clé permet

1. La portée de la clé

2. Les droits de l'utilisateur Acomba

Erreurs d'authentification

Plusieurs dossiers Acomba

Bonnes pratiques