Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

Jetons d'accès personnels

Un jeton d'accès personnel (PAT) est un identifiant que vous créez et collez vous-même. Il est destiné à l'API REST de Waafir et aux scripts, ainsi qu'à un assistant IA qui ne peut pas se connecter : la plupart des assistants se connectent en collant l'URL de Waafir et en s'authentifiant, sans aucun jeton. Sur les serveurs MCP de Waafir, chaque requête porte soit une connexion créée par authentification, soit un PAT valide. Aucun accès anonyme n'existe, et une session de navigateur authentifiée ordinaire n'est pas acceptée sur cette surface (une requête authentifiée par session est rejetée). Un PAT agit en votre nom, au sein de votre organisation, dans les limites de la portée et des salles de données que vous choisissez lors de son émission.

Où émettre un jeton

Ouvrez Modules complémentaires → Configuration → Jetons API. La page comporte trois parties : un formulaire pour émettre un nouveau jeton, la liste de vos jetons existants (avec une action de révocation), et un extrait de configuration prêt à l'emploi pour connecter un assistant avec un jeton.

Pour émettre un jeton, remplissez le formulaire :

  • Nom — un libellé lisible pour reconnaître le jeton plus tard (par exemple « Claude Desktop – portable »). Obligatoire.
  • Portée — ce que le jeton est autorisé à faire. Voir ci-dessous.
  • Portée de la salle de données — laissez Toutes les salles de données coché pour que le jeton atteigne toutes les salles de données auxquelles vous avez accès, ou décochez-le et sélectionnez des salles de données précises pour limiter le jeton à celles-ci.
  • Expiration — la date après laquelle le jeton cesse de fonctionner. Facultative à renseigner, mais pas facultative dans les faits : laissez-la vide et le jeton est émis avec une expiration de 90 jours. Voir Expiration.

Portées

Un jeton porte l'une de trois portées, par ordre croissant d'autorité :

PortéeAutoriseUsage type
readLister et lire — salles de données, dossiers, fichiers, métadonnées de fichiers, recherche, URL de téléchargement et consultation des permissions ; lire le texte extrait d'un document ; lire les fils de Q&R des investisseurs ; vérifier l'état d'une tâche de caviardage, de traduction ou de signature électronique.Un assistant en lecture seule qui répond à des questions sur une salle de données.
writeTout ce que read autorise, plus les modifications : créer, renommer, déplacer, supprimer et restaurer des dossiers ; téléverser, renommer, déplacer, supprimer et restaurer des fichiers, y compris téléverser une nouvelle version d'un fichier et revenir à une version antérieure ; lancer le caviardage ou la traduction d'un document ; et créer, envoyer, refuser et annuler des enveloppes de signature électronique. Envoyer une enveloppe (ou ajouter des signataires à une enveloppe déjà envoyée) nécessite aussi Envoyer à des personnes en dehors de votre organisation, et votre assistant vous demande de confirmer avant l'envoi. Signer (esign_sign) nécessite aussi Signer des documents, et est de même confirmé au préalable.Un assistant qui organise ou tient à jour une salle de données.
adminTout ce que write autorise, plus les quatre outils d'attribution de permissions : accorder ou révoquer l'accès d'un utilisateur à des fichiers et à des salles de données. Notez que les trois outils de lecture des permissions n'exigent que read.Un assistant qui gère qui peut voir quoi.

La portée est cumulative — une portée supérieure inclut tout ce qui est en dessous. La référence des outils de chaque serveur indique la portée minimale requise par chaque outil.

Qui peut émettre chaque portée

Un jeton ne peut jamais porter plus d'autorité que la personne qui l'émet :

  • read et write peuvent être émis par tout membre actif de votre organisation.
  • admin ne peut être émis que par un propriétaire ou administrateur de l'organisation. Si vous n'êtes ni propriétaire ni administrateur, l'option admin n'apparaît pas dans le sélecteur de portée.
  • Les investisseurs (et les autres rôles hors équipe de transaction) ne peuvent pas émettre de jetons du tout.

Au-delà de l'émission, les outils de permission admin appliquent un second plafond au moment de l'appel : le propriétaire du jeton doit lui-même être administrateur ou responsable dans l'organisation pour qu'une attribution de permission aboutisse. La portée d'un jeton est le plafond du jeton ; le rôle du propriétaire est le plafond de la personne, et une action d'administration doit franchir les deux — exactement la règle qu'applique l'interface du produit. Il n'existe pas de chemin plus permissif via MCP que via le produit.

Autoriser un jeton à signer des documents

Signer nécessite un jeton avec Signer des documents activé. Vous le choisissez lorsque vous créez le jeton dans Modules complémentaires → Configuration, pour un jeton write ou admin, afin que seul un assistant auquel vous avez accordé votre confiance puisse signer pour vous. La création d'un jeton demande déjà votre code à deux facteurs lorsque l'authentification à deux facteurs est activée, si bien que cette vérification couvre chaque signature que fait le jeton. La liste des jetons affiche Peut signer pour chacun de ces jetons.

Votre assistant vous montre d'abord les documents, le signataire et les champs, et ne signe que lorsque vous confirmez. Un jeton sans Signer des documents ne voit pas esign_sign dans sa liste d'outils, et il est refusé s'il l'appelle. Les jetons créés avant l'existence de cette option ne peuvent pas signer : créez-en un nouveau avec Signer des documents activé.

Autoriser un jeton à lire le contenu des documents

Lire un document en entier, ou interroger l'IA sur des documents, nécessite un jeton avec Lire le contenu des documents activé. Vous le choisissez lorsque vous créez le jeton dans Modules complémentaires → Configuration, quelle que soit la portée. La liste des jetons affiche Contenu du document pour chacun de ces jetons. Cela couvre :

  • get_file_text, le texte extrait complet d'un document ;
  • get_file_download_url, un lien de téléchargement d'un fichier ;
  • esign_download_signed, un PDF signé électroniquement ;
  • le lien de téléchargement que translate_file_status renvoie pour une traduction terminée ;
  • GET /api/v1/files/{fileId}/content, les octets du document via l'API REST ;
  • POST /api/viewer/token, POST /api/viewer/artifact-access et POST /api/viewer/artifact-access/unlock, qui génèrent le jeton ou le cookie de visionneuse avec lequel la visionneuse de documents intégrée au produit diffuse un document ;
  • les outils d'IA dont vous rédigez la question ou l'entrée, puisqu'une réponse peut reprendre ce que dit un document : dataroom_ask, dataroom_draft_answer, dataroom_compare_files et dataroom_generate_update ;
  • POST /api/v1/chat, la même réponse d'IA via l'API REST ;
  • la quote de chaque fait que renvoie GET /api/v1/facts.

Un jeton qui n'en dispose pas se voit refuser ces outils (GRANT_REQUIRED) et ces routes REST (PAT_GRANT_REQUIRED), et translate_file_status renvoie l'état avec download_withheld_reason: content_grant_required au lieu d'un lien. GET /api/v1/facts et dataroom_list_facts renvoient chaque fait sans sa quote, avec value tronquée à 20 mots et value_truncated défini. Le jeton peut toujours lister et rechercher, et lire le résumé d'un document avec get_file_metadata ou dataroom_summarise_file. Les jetons créés avant l'existence de cette option ne peuvent pas lire le contenu des documents : créez-en un nouveau avec Lire le contenu des documents activé. Les jetons de service ne sont pas concernés.

Chaque jeton peut obtenir au plus 10 liens de téléchargement par minute. Au-delà, get_file_download_url est refusé (RATE_LIMITED) et translate_file_status renvoie l'état avec download_withheld_reason: rate_limited ; redemandez au bout d'une minute.

Autoriser un jeton à envoyer à des personnes en dehors de votre organisation

Créer un lien de partage, ajouter un lecteur d'instantané, inviter un membre de l'équipe ou un investisseur, et prolonger ou rétablir l'accès d'un investisseur (dataroom_extend_investor_access, dataroom_reinstate_investor_access) donnent accès à quelqu'un en dehors de votre organisation ; ces actions nécessitent donc un jeton avec Envoyer à des personnes en dehors de votre organisation activé (la même autorisation que celle qui envoie les mises à jour aux investisseurs, les réponses aux Q&R et les demandes de signature électronique). Vous la choisissez lorsque vous créez un jeton write ou admin dans Modules complémentaires → Configuration. La liste des jetons affiche Peut envoyer à l'extérieur pour chacun de ces jetons.

Votre assistant vous montre d'abord qui un nouveau lien admet, la règle de NDA et l'expiration, et ne le crée que lorsque vous confirmez. Révoquer un lien ou un lecteur ne nécessite aucune autorisation.

L'autorisation couvre aussi le fait de donner à quelqu'un en dehors de votre équipe de transaction (propriétaires, administrateurs et membres) un accès, ou davantage d'accès, à une salle de données ou à un document. « En dehors » désigne toute personne qui n'est pas membre actif de l'équipe de transaction de l'organisation de la salle : investisseurs, invités, personnes ayant une invitation en attente et membres d'une autre organisation. Sans cette autorisation, un jeton est refusé (GRANT_REQUIRED sur MCP) pour :

  • une autorisation de lecture ou de téléchargement accordée à une telle personne : set_file_permissions, dataroom_set_folder_permissions, dataroom_bulk_set_file_permissions ;
  • la levée d'un refus visant une telle personne, qui rétablit son accès : revoke_file_permission, dataroom_revoke_folder_permission, dataroom_bulk_revoke_file_permissions ;
  • l'accès à une salle pour une telle personne, à quelque niveau que ce soit : invite_user_to_dataroom ;
  • le changement de rôle d'un membre dont le rôle actuel ne relève pas de l'équipe de transaction, ce qui le promeut : dataroom_team_change_member_role ;
  • une modification d'investisseur qui élargit l'accès : dataroom_set_investor_permissions de lecteur à téléchargeur, la désactivation du NDA, ou l'activation du suivi ou des mises à jour.

Les refus, la fin d'une autorisation et les autorisations accordées à votre équipe de transaction ne nécessitent aucune autorisation. Le contenu placé là où une personne a déjà accès (téléversement, déplacement, publication) n'est pas couvert. Joindre un NDA de société que la société a signé ne nécessite aucune autorisation.

La même autorisation s'applique à ces appels REST effectués avec un jeton d'accès personnel :

  • POST /api/share-links (créer un lien) et POST /api/snapshots/{id}/viewers sont refusés avec 403 PAT_GRANT_REQUIRED sans elle ;
  • POST /api/investors/invite (qui crée un lien personnel et l'envoie par e-mail) est refusé de la même manière ;
  • PATCH /api/investors/{id}/extend et PATCH /api/investors/{id}/access (rétablir un investisseur ou approuver une demande d'accès) sont refusés de la même manière ; révoquer un investisseur (DELETE /api/investors/{id}/access) ne nécessite aucune autorisation ;
  • POST /api/team, POST /api/v1/team et POST /api/team/resend (une invitation d'équipe envoie par e-mail un lien d'adhésion) sont refusés de la même manière ;
  • PATCH /api/share-links/{id} est refusé pour toute modification des paramètres d'accès d'un lien (son activation, son mode, ses domaines, son expiration ou son NDA, que la modification les élargisse ou les resserre) ; désactiver un lien est toujours autorisé ;
  • GET /api/share-links répond sans l'url ni le token de chaque lien, marqués urlWithheld: true, avec un urlWithheldReason qui en indique la raison ;
  • POST /api/v1/grants est refusé pour une autorisation de lecture ou de téléchargement accordée à une personne hors de l'équipe de transaction ; DELETE /api/v1/grants/{id} est refusé lorsque l'autorisation est le refus visant cette personne ; PATCH /api/v1/team/{id} est refusé lorsque le rôle actuel du membre ne relève pas de l'équipe de transaction.

Ces contrôles lisent le chemin tel que le serveur le route, de sorte qu'une barre oblique finale ou un caractère encodé en pourcentage ne permet pas de les contourner. Un chemin qui ne peut pas être décodé, ou qui comporte un segment ./.. ou un / encodé à l'intérieur d'un segment, ne peut être rapproché d'aucun des appels couverts par une autorisation. Ainsi, un jeton d'accès personnel auquel il manque une quelconque autorisation par requête — celle-ci, Lire le contenu des documents ou Lire les analyses d'engagement — voit chacun de ces chemins refusé avec 403 PAT_PATH_MALFORMED, quel que soit l'appel.

Les jetons créés avant l'existence de cette autorisation ne la détiennent pas ; ils perdent donc ces appels jusqu'à ce que vous créiez un nouveau jeton write ou admin avec l'option activée. Un jeton read ne peut pas détenir cette autorisation.

Autoriser un jeton à lire les analyses d'engagement

Lire les analyses d'engagement permet à un jeton de lire qui a consulté quels documents, quand et pendant combien de temps : les outils d'engagement, et les données d'engagement de la liste des investisseurs. Ne l'activez que pour un assistant qui doit voir ces informations. Toute portée peut la détenir.

La même autorisation s'applique aux lectures d'activité REST : GET /api/v1/activity (le flux d'activité et d'audit de l'organisation), /api/v1/activity/rollups, /api/v1/activity/engagement, /api/v1/activity/engagement/documents et /api/v1/activity/engagement/document/pages. Sans elle, un jeton d'accès personnel est refusé avec 403 PAT_GRANT_REQUIRED. Les jetons de service et les sessions authentifiées ne sont pas concernés.

Les jetons créés avant l'existence de ces options n'en ont aucune : créez-en un nouveau avec l'option activée.

Restreindre un jeton à des salles de données précises

Par défaut, un jeton peut atteindre toutes les salles de données auxquelles son propriétaire a accès. Décocher Toutes les salles de données et sélectionner des salles précises limite le jeton à cette liste autorisée : tout appel d'outil qui fait référence à une salle de données hors de la liste est rejeté, et un jeton ainsi limité ne voit même pas les noms des salles de données qu'il ne peut pas ouvrir. Utilisez cette option pour donner à un client IA l'accès à une seule opération sans exposer le reste de votre portefeuille.

Expiration

Tout jeton expire. Il n'existe pas de PAT perpétuel : un jeton qui n'expirait jamais était lui-même la faille de sécurité que ce comportement vise à corriger, car un identifiant oublié reste valide indéfiniment. Définir une date d'expiration fait cesser le jeton de fonctionner après cette date — une requête avec un jeton expiré est rejetée exactement comme avec un jeton révoqué, avec HTTP 401.

  • Laissez le champ vide et vous obtenez 90 jours, comptés à partir du moment où le jeton est émis. Vide signifie utiliser la valeur par défaut, et non ne jamais expirer.
  • Définissez une date et elle est respectée exactement, jusqu'à un plafond de 365 jours à compter de l'émission.
  • Demandez plus de 365 jours et la demande est refusée, et non discrètement raccourcie — l'émission ne vous remet jamais un jeton à durée de vie plus courte que celle demandée sans vous le dire. Une date passée est refusée de la même manière.

Ainsi, si une intégration est censée continuer à fonctionner, définissez l'expiration de façon délibérée et inscrivez un rappel dans votre agenda pour remplacer le jeton avant son échéance — un champ vide arrêtera silencieusement cette intégration environ trois mois après sa mise en place. Il n'existe aucune action de renouvellement ou de rotation sur un jeton existant ni aucun avertissement avant son expiration : en remplacer un signifie émettre un nouveau jeton, mettre à jour la configuration de votre client et révoquer l'ancien. À l'inverse, une expiration courte convient parfaitement à un jeton émis pour une tâche ponctuelle.

La liste des jetons dans Modules complémentaires → Configuration affiche l'expiration de chaque jeton, afin que vous puissiez voir ce qui arrive à échéance.

L'affichage unique

Lorsque vous émettez un jeton, la valeur brute — elle commence par waafir_pat_ — est affichée une seule fois, immédiatement après sa création. Waafir ne stocke jamais le jeton brut, seulement une empreinte à sens unique, de sorte qu'il ne peut pas être récupéré ni affiché à nouveau.

  • Copiez-le maintenant et collez-le directement dans la configuration de votre client. Le panneau d'affichage dispose d'un bouton de copie.
  • Si vous le perdez, vous ne pouvez pas le récupérer — révoquez ce jeton et émettez-en un nouveau.
  • Traitez-le comme un mot de passe : il confère sa portée à quiconque le détient.

Après l'affichage, la liste des jetons ne montre plus qu'un court préfixe non secret (par exemple waafir_pat_ab12…) afin que vous puissiez distinguer vos jetons sans que le secret soit récupérable.

Révoquer un jeton

Dans la liste des jetons de Modules complémentaires → Configuration, utilisez l'action Révoquer à côté de n'importe quel jeton. La révocation est immédiate — la requête suivante utilisant le jeton est rejetée. Révoquez un jeton dès qu'un appareil est perdu, qu'un prestataire s'en va, ou simplement que vous n'avez plus besoin de l'accès. Les jetons révoqués restent visibles dans la liste (marqués comme révoqués) afin de conserver la trace de ce qui a existé ; ils ne peuvent jamais être réactivés.

Quand un jeton prend fin de lui-même

Un jeton agit au travers de votre appartenance à l'organisation ; il prend donc fin lorsque cette appartenance prend fin. Vous n'avez pas besoin de le révoquer vous-même lorsque :

  • Vous quittez l'organisation, ou un administrateur vous en retire. Chaque jeton que vous détenez dans cette organisation est révoqué à ce moment-là. Les jetons que vous détenez dans d'autres organisations continuent de fonctionner.
  • Un administrateur Waafir supprime votre compte. Vos jetons dans toutes les organisations sont révoqués.
  • Un administrateur Waafir supprime l'organisation. Tous les jetons qu'elle contient sont révoqués, y compris ses jetons de service.

Ces révocations sont définitives. Être invité de nouveau, ou voir votre compte ou l'organisation restauré, ne fait pas revenir un jeton : émettez-en un nouveau.

Un jeton de service appartient à l'organisation, et non à l'administrateur qui l'a créé ; il continue donc de fonctionner lorsque cet administrateur s'en va. Seule sa révocation, ou la suppression de l'organisation, y met fin de manière anticipée.

L'historique des jetons dans le journal d'audit

Chaque jeton émis ou révoqué inscrit une ligne dans le journal d'audit de l'organisation : qui l'a fait, le nom du jeton, sa portée, ses permissions et son expiration, le nombre de salles de données auxquelles il est limité, et la raison de sa révocation (par son propriétaire, parce qu'une appartenance a pris fin, ou parce qu'un compte ou une organisation a été supprimé). Le jeton lui-même, son empreinte et son préfixe ne sont jamais enregistrés. Les lignes apparaissent dans la piste d'activité complète, et non dans le résumé du tableau de bord.

Si Waafir ne parvient pas à enregistrer un nouveau jeton dans le journal d'audit, le jeton n'est pas émis et vous voyez « The token wasn't created because we couldn't record it. Try again. »

Étape suivante : configurez votre client avec le jeton que vous venez d'émettre.