Clés API

Pour :Administrateur

Vue de la page « cles api »

Une clé API est un identifiant secret qui permet à un outil externe (Make, n8n, Zapier, un script maison, un CRM…) de lire les données de votre organisation Unisoft en votre nom. Cette page explique comment créer, gérer et révoquer ces clés en toute sécurité.

Ouvrir l'onglet Clés API

1. 1

   Aller sur la page Développeurs

   Tapez l'URL /app/developpeurs/tabs dans la barre d'adresse, ou ouvrez votre favori.

2. 2

   Onglet « Clés API »

   L'onglet est sélectionné par défaut à l'ouverture de la page.

Comprendre le tableau

Le tableau central liste les clés API existantes de votre organisation. Pour chacune, vous voyez :

Colonne	Contenu
Nom	Le libellé que vous avez choisi à la création (ex. Make - sync Mailchimp)
Préfixe	Les 12 premiers caractères de la clé suivis de … (par exemple ke_live_abcd…), affichés en clair pour vous permettre de la reconnaître dans la liste. La clé complète n'est jamais réaffichée après création.
Permissions	Les scopes accordés (tags) — ce que la clé peut lire
Dernière utilisation	Date relative du dernier appel API effectué avec cette clé, ou jamais
Statut	Active (vert), Révoquée (rouge), ou Inactive (gris)
Actions	Boutons Révoquer et Supprimer

★

Repérer une clé abandonnée

Si la colonne Dernière utilisation indique jamais ou il y a plusieurs mois, c'est probablement une clé orpheline. Révoquez-la pour réduire votre surface de risque.

Créer une nouvelle clé

1. 1

   Cliquer sur « Nouvelle clé »

   Le bouton se trouve en haut à droite de l'onglet. Une modale s'ouvre.

2. 2

   Donner un nom évocateur

   Saisissez un nom descriptif comme Make production, Zapier Mailchimp, ou Script export comptable. Vous vous y retrouverez plus tard quand vous aurez plusieurs clés.

3. 3

   Choisir les permissions

   Sélectionnez les scopes (permissions) que la clé pourra utiliser. Par défaut, toutes les permissions de lecture seule sont pré-sélectionnées. Voir la table ci-dessous pour le détail.

4. 4

   Cliquer sur « Créer la clé »

   Une nouvelle modale s'affiche immédiatement avec la clé brute.

5. 5

   Copier la clé sans attendre

   Cliquez sur « Copier la clé » ou utilisez l'icône de copie. Vous ne reverrez jamais cette clé une fois la modale fermée — collez-la immédiatement dans votre outil ou votre gestionnaire de mots de passe.

6. 6

   Confirmer

   Cliquez sur « J'ai bien copié la clé » pour fermer la modale.

⛔

Affichée une seule fois

Pour des raisons de sécurité, la clé brute (au format ke_live_...) n'est affichée qu'une seule fois, juste après sa création. Si vous fermez la modale sans la copier, vous devrez créer une nouvelle clé et supprimer celle-ci. Unisoft ne stocke que l'empreinte cryptographique de la clé, jamais la clé en clair.

Les permissions disponibles

Chaque scope autorise un type d'accès précis. Cochez uniquement ce dont votre intégration a besoin.

Scope	Ce qu'il autorise
contacts:read	Lire la liste et les fiches des contacts
paiements:read	Lire les paiements encaissés
abonnements:read	Lire les paiements récurrents (abonnements)
forms:read	Lire les définitions des formulaires
forms_submit:read	Lire les soumissions envoyées par vos formulaires
webhooks:manage	Gérer les webhooks sortants via API (créer, modifier, supprimer)

ℹ

Permissions d'écriture à venir

Les permissions en lecture seule sont actuellement disponibles. Les permissions d'écriture (création de contacts ou de paiements via API) seront ajoutées dans une prochaine version.

Utiliser la clé dans un outil externe

Une fois la clé en main, voici comment elle s'utilise :

Dans un appel HTTP brut

Toutes les requêtes vers l'API Unisoft doivent inclure la clé dans l'entête HTTP Authorization au format Bearer :

GET /integrations/v1/contacts HTTP/1.1
Host: api.unisoft.world
Authorization: Bearer ke_live_xxxxxxxxxxxxxxxxxxxxx

Dans Make / Integromat

1. Créez une connexion HTTP ou Webhook.
2. Type d'authentification : Bearer Token (ou Header selon le module).
3. Valeur : votre clé ke_live_....

Dans n8n

1. Ajoutez un nœud HTTP Request.
2. Authentication : Header Auth.
3. Nom : Authorization, Valeur : Bearer ke_live_....

Dans Zapier

1. Choisissez l'action Webhook by Zapier → Custom Request.
2. Headers : ajoutez Authorization: Bearer ke_live_....

Pour la liste complète des endpoints (URL, paramètres, format des réponses), consultez la documentation Swagger via le bouton « Documentation API » en haut à droite de la page Développeurs.

Révoquer une clé

La révocation désactive immédiatement la clé. Toute intégration qui l'utilise s'arrête à la requête suivante.

1. 1

   Repérer la clé dans le tableau

   Identifiez la clé par son nom ou son préfixe.

2. 2

   Cliquer sur « Révoquer »

   Le bouton se trouve dans la colonne Actions. Une demande de confirmation apparaît.

3. 3

   Confirmer

   Confirmez la révocation. Le statut de la clé passe à Révoquée (tag rouge). Elle ne pourra plus jamais être réactivée.

⚠

Quand révoquer ?

Révoquez sans hésiter dans ces cas : un développeur quitte l'organisation, un outil externe a été compromis, une clé apparaît dans un email ou un dépôt Git par inadvertance, vous découvrez une clé que vous ne reconnaissez plus.

Supprimer une clé

La suppression efface la clé du tableau. Elle n'est plus listée, mais le résultat fonctionnel est le même qu'une révocation : la clé ne fonctionne plus.

1. 1

   Cliquer sur l'icône Supprimer

   Icône de poubelle rouge dans la colonne Actions.

2. 2

   Confirmer

   La clé disparaît du tableau.

Préférez la révocation à la suppression si vous voulez garder la trace d'une clé pour l'audit. Réservez la suppression au nettoyage des vieilles clés sans intérêt historique.

Cas pratique : configurer Make pour synchroniser les contacts avec Mailchimp

1. 1

   Créer une clé dédiée

   Nom : Make - sync Mailchimp. Permission : uniquement contacts:read (rien d'autre).

2. 2

   Copier la clé dans le presse-papiers

   Conservez-la dans votre gestionnaire de mots de passe ou collez-la directement dans Make à l'étape suivante.

3. 3

   Configurer le scénario Make

   Module : HTTP → Make a request. URL : https://api.unisoft.world/integrations/v1/contacts. Method : GET. Header : Authorization: Bearer ke_live_....

4. 4

   Tester le scénario

   Make doit recevoir la liste des contacts. Si oui, branchez la suite (Mailchimp → Add/Update Subscriber).

5. 5

   Programmer l'exécution

   Configurez la fréquence souhaitée (toutes les heures, tous les jours…). Le scénario tournera de manière autonome.

Bonnes pratiques de sécurité

Règle	Pourquoi
Une clé par intégration	Si une clé est compromise, vous la révoquez sans casser les autres outils
Minimum de permissions	Ne cochez que les scopes strictement nécessaires
Stockage dans un coffre-fort	Gestionnaire de mots de passe (1Password, Bitwarden, KeePass…) ou variables d'environnement de votre outil — jamais en clair dans un fichier
Surveillance régulière	Vérifiez la colonne Dernière utilisation chaque trimestre. Une clé inactive est un risque inutile
Rotation périodique	Pour les intégrations critiques, créez une nouvelle clé tous les 6-12 mois et révoquez l'ancienne

Pièges à éviter

Piège	Conséquence	Solution
Fermer la modale sans avoir copié la clé	Clé perdue, intégration impossible	Recréer une clé et supprimer la précédente
Stocker la clé dans un email ou un Slack	Compromission possible	Toujours utiliser un gestionnaire de mots de passe
Cocher toutes les permissions par habitude	Surface d'attaque maximale	Décocher ce dont l'intégration n'a pas besoin
Réutiliser la même clé pour plusieurs outils	Difficile de tracer qui appelle quoi	Une clé = un outil = un nom évocateur

À retenir

• Une clé API permet à un outil externe de lire les données Unisoft de votre organisation.
• La clé brute est affichée une seule fois à la création — copiez-la immédiatement.
• Le bouton « Révoquer » stoppe instantanément toute intégration qui utilise la clé.
• Une clé par usage et minimum de permissions sont les deux règles d'or.

Aller plus loin

• Vue d'ensemble Développeurs — les deux briques d'intégration
• Webhooks sortants — recevoir des notifications en temps réel