Créer une clé API

Les clés API permettent à un autre système de piloter AssinaJá — votre ERP qui crée des documents, ou un assistant IA qui travaille via l’interface MCP. Créez-en une pour chaque système externe ou assistant IA, avec des accès limités à ce dont cette intégration a besoin.

Paramètres → Développeurs comporte les onglets Général, Clés API, Webhooks, Intégrations et Stockage — les deux derniers sont réservés au Créateur et à l’Administrateur. Général s’ouvre en premier, avec les adresses de l’API publique et du Serveur MCP et le lien Ouvrir la documentation de l’API.

Les clés se trouvent dans Clés API, et seul le Créateur de l’organisation les gère. Pour un autre rôle, l’onglet s’ouvre mais n’affiche pas les clés.

Une clé par intégration

Créez une clé pour chaque système externe qui s’intègre à l’API publique (en-tête X-Api-Key). Chaque clé peut être suspendue ou supprimée individuellement, sans affecter les autres intégrations.

C’est la raison d’être de cette règle : une clé partagée ne peut pas être révoquée sans tout casser chez ceux qui l’utilisent. Une clé par système permet de couper une intégration en laissant les autres fonctionner.

En créer une

Choisissez Nouvelle clé API.

1. Nom — donnez-lui le nom du système qui va l’utiliser, par exemple ERP Sage. Si vous le souhaitez, ajoutez une Description.
2. Date d’expiration — « La clé est valable jusqu’à cette date incluse (elle cesse de s’authentifier à la fin de ce jour). »
3. Accès — cochez uniquement ce dont cette intégration a besoin. Au moins un accès est obligatoire : « Sélectionnez au moins un accès — la clé ne peut faire que ce qui est coché. »
4. Créer la clé.

La clé n’est affichée qu’une seule fois

Copiez et conservez cette clé maintenant : elle ne sera plus jamais affichée et n’est conservée nulle part. Si vous la perdez, utilisez « Renouveler la clé » pour en générer une autre avec les mêmes accès.

Il n’existe aucun moyen de la récupérer ensuite. À côté de Copier se trouve Copier comme variable d’environnement, qui copie ASSINAJA_API_KEY= suivi de la clé, prêt à coller dans un fichier de configuration. La boîte de dialogue ne se ferme qu’après avoir coché J’ai conservé la clé en lieu sûr.

Accès

Accès	Ce qu’il permet
Modèles — consulter	Lister et consulter les modèles, y compris les signataires et les champs à remplir.
Documents — consulter	Lister les documents, suivre l’avancement des signatures et télécharger les fichiers et les rapports.
Documents — liens de signature	Obtenir les liens de signature des signataires en attente. Quiconque détient le lien signe au nom du signataire — c’est un identifiant d’accès, pas une simple consultation.
Documents — créer	Créer des documents à partir de modèles, de DOCX (MailMerge) ou d’un PDF personnel.
Documents — publier	Publier des brouillons — envoie des e-mails aux signataires et est irréversible.
Documents — archiver/supprimer	Archiver et supprimer des documents.
Organisation — consulter	Voir les données de l’organisation, le forfait actif et les fonctionnalités disponibles.
Statistiques — consulter	Lire les indicateurs agrégés de l’organisation : utilisation, entonnoir de signature et adoption. Jamais par personne. Ne fonctionne que si Paramètres → Politiques → Accès de l’IA aux statistiques l’autorise aussi.
Webhooks — secret de signature	Lire et renouveler le secret avec lequel nous signons les webhooks que nous envoyons, pour que le système destinataire puisse valider l’en-tête X-AssinaJa-Signature. À n’accorder qu’aux intégrations de webhooks : ce secret permet de signer des événements.
Catalogue de modèles	Uniquement avec le forfait Enterprise — voir ci-dessous.

Publier, c’est l’accès dangereux

Documents — publier envoie des e-mails aux signataires et est irréversible. Créer et publier sont des accès volontairement séparés, pour qu’une intégration puisse préparer des brouillons qu’une personne relira, sans jamais pouvoir les envoyer. Ne l’accordez que si le système doit vraiment envoyer seul.

Pour un assistant IA, commencez sans l’accès de publication

Pour une première connexion via MCP, cochez Modèles — consulter, Documents — consulter et Documents — créer, et laissez Documents — publier de côté. L’assistant prépare tout et laisse le document en brouillon ; l’envoi reste un acte que vous effectuez vous-même, dans l’application. Une fois que vous avez vu comment il se comporte, ajoutez l’accès de publication si vous le souhaitez.

Documents — consulter ne donne pas les liens de signature : ceux-ci ont leur propre accès, Documents — liens de signature, car quiconque détient un lien signe à la place du signataire. Ne l’accordez qu’à une intégration qui doit réellement remettre les liens.

Statistiques — consulter nécessite aussi la politique de l’organisation — voir Accès de l’IA aux statistiques.

L’accès au catalogue de modèles

Catalogue de modèles — servir d’autres organisations est différent des autres :

Permet à d’autres organisations de générer des documents à partir du catalogue de modèles de cette organisation (en-tête X-Api-Key-TemplateCatalog). Ne donne aucun autre accès.

Il utilise son propre en-tête et n’accorde rien d’autre. Il est Disponible uniquement avec le forfait Enterprise.

Une clé disposant de cet accès est partagée avec d’autres organisations : elle ne peut donc avoir aucun accès Documents en plus, et la plateforme refuse de l’enregistrer ainsi. Pour le catalogue, utilisez une clé distincte.

Les modèles via l’API publique : deux règles

Ce sont des règles de l’API publique, valables pour toute clé qui consulte des modèles :

• Le forfait qui compte est celui de l’organisation qui fournit le modèle, pas celui de l’appelant. Si l’organisation propriétaire du catalogue n’a pas les Modèles activés, les cinq endpoints qui utilisent des modèles répondent 423 FEATURE_TEMPLATES_NOT_ENABLED.
• Les brouillons n’existent pas pour l’API. Ils n’apparaissent pas dans la liste, et demander le détail de l’un d’eux renvoie 404. Publiez le modèle avant de l’intégrer.

Gérer les clés

La liste affiche Nom, Clé, Accès, Validité, Statut, Créée et Dernière utilisation — cette dernière indique Jamais pour une clé qui ne s’est jamais authentifiée. Cette colonne est le moyen le plus rapide de repérer une clé que personne n’utilise.

Action	Effet
Modifier	Changer le nom, la validité ou les accès
Renouveler la clé	Générer un nouveau secret pour la même intégration — voir ci-dessous
Suspendre	« Une fois suspendue, la clé ne permet plus de s’authentifier jusqu’à sa réactivation. »
Activer	Réactiver une clé suspendue
Supprimer	Définitif

Le Statut d’une clé est Active, Suspendue ou Expirée.

Renouveler une clé

Lorsque vous perdez une clé, ou soupçonnez qu’elle a été exposée, vous n’avez pas besoin de la supprimer et de reconfigurer l’intégration de zéro. Renouveler la clé ouvre Renouveler la clé — « Une nouvelle clé est générée pour cette intégration. Le nom, les accès, la validité et les assistants IA associés sont conservés ; seul le secret change. » — et vous demande quand La clé actuelle cesse de fonctionner :

Option	Quand l’utiliser
Immédiatement — à utiliser si la clé a pu être exposée	« L’intégration qui utilise la clé actuelle ne pourra plus s’authentifier dès le renouvellement. »
Dans 1 heure — le temps de la remplacer dans le système qui l’utilise	L’option par défaut : les deux clés fonctionnent pendant une heure.
Dans 24 heures	Idem, avec une journée de marge.

La nouvelle clé n’est affichée qu’une seule fois, comme à la création — Clé renouvelée, avec « L’ancienne clé continue de fonctionner jusqu’au {date}. Remplacez-la d’ici là dans le système qui l’utilise. » ou, si vous avez choisi immédiatement, « L’ancienne clé ne fonctionne plus. » Dans la liste, la clé affiche alors Renouvelée le {date} et, tant que dure le chevauchement, « L’ancienne fonctionne jusqu’au {date} ».

Une clé Expirée ne se renouvelle pas — « Expirée : créez une nouvelle clé au lieu de la renouveler. »

Suspendez avant de supprimer

La suspension est réversible ; la suppression ne l’est pas — « est irréversible — l’intégration qui l’utilise ne pourra immédiatement plus s’authentifier. » Si vous soupçonnez qu’une clé est compromise ou inutilisée, suspendez-la et observez ce qui cesse de fonctionner. Vous pouvez toujours la réactiver.

Être averti lorsqu’un événement se produit

Pour que votre système soit averti lorsqu’un événement concerne un document, au lieu de devoir interroger la plateforme, voir Recevoir des webhooks.

Voir aussi

• Recevoir des webhooks
• Rôles et autorisations — les clés API et les webhooks sont réservés au Créateur ; Intégrations et Stockage, au Créateur et à l’Administrateur
• Configurer les politiques de l’organisation