Aller au contenu

Jetons d'API

Pourquoi c'est important

Un jeton d'API est comme un mot de passe mais pour des programmes, pas pour des personnes. Il permet à des applications externes (un autre outil de votre cabinet, un script automatisé, un Zapier) de lire ou écrire des données dans ImmCase sans avoir à se connecter comme un utilisateur humain.

Usages typiques :

  • Synchroniser votre base de demandeurs avec Mailchimp ou HubSpot.
  • Connecter ImmCase avec un système comptable externe.
  • Automatiser des tâches avec des scripts (importer des données d'un Excel périodique).
  • Application mobile personnalisée qui lit des données d'ImmCase.

Créer un jeton

  1. Barre latérale → Paramètres → Jetons d'API → Créer.
  2. Remplissez :
  3. Nom du jeton (pourquoi il existe — « Synchro Mailchimp », « Script importateur »).
  4. Portée (scope) — ce que peut faire le jeton. Lecture seule, lecture+écriture, modules précis.
  5. Expiration — date à laquelle le jeton cesse de fonctionner. Recommandé : maximum 1 an.
  6. Générer.
  7. Copiez le jeton tout de suite — il n'est affiché qu'une fois. Si vous le perdez, vous en générez un nouveau.

Capture d'écran : écran de création avec le jeton fraîchement généré et l'avis de copier

Utiliser le jeton

Celui qui consomme l'API d'ImmCase inclut le jeton dans chaque requête HTTP :

Authorization: Bearer <votre-jeton>

La documentation technique complète de l'API est maintenue par l'équipe de développement. Pour les administrateurs : ce qui compte, c'est de générer le bon jeton avec les permissions minimales nécessaires.

Révoquer un jeton

Si un jeton est compromis (vous l'avez poussé par erreur dans un dépôt public, quelqu'un l'a exposé) :

  1. Ouvrez le jeton → Révoquer immédiatement.
  2. Générez-en un nouveau.
  3. Mettez à jour l'application qui l'utilisait.

Le jeton révoqué cesse de fonctionner à l'instant. Les requêtes avec l'ancien jeton reçoivent 401 Unauthorized.

Audit d'usage

Chaque jeton a un journal d'usage :

  • Dernière fois utilisé.
  • Combien de requêtes au dernier jour/semaine/mois.
  • Depuis quelles IP.

Utile pour détecter un usage anormal — si un jeton « Synchro Mailchimp » se met à faire des milliers de requêtes depuis une IP inhabituelle, il y a un problème.

Bonnes pratiques

  • Un jeton par intégration, pas un jeton « tout-en-un ». Révoquer un n'en casse pas tout.
  • Permissions minimales — s'il n'a besoin que de lire les demandeurs, ne lui donnez pas la permission de supprimer.
  • Expiration courte — faire tourner les jetons chaque année est une bonne hygiène.
  • Jetons en variables d'environnement, pas dans le code. Ne poussez jamais un jeton dans Git.

À surveiller

  • Les jetons sont des secrets. Traitez chaque jeton comme un mot de passe. S'il fuit, révoquez.
  • Jetons sans portée = porte ouverte. Un jeton sans restriction peut faire tout ce qu'un utilisateur ferait. Limitez toujours.
  • Ne réutilisez pas les jetons entre environnements (production et test). Si quelque chose se passe en test, vous ne voulez pas que ça affecte la production.

Pour la suite