Waafir
Diese Seite ist eine maschinelle Übersetzung, die noch auf eine menschliche Prüfung wartet. Sie kann Fehler enthalten.

Persönliche Zugriffstokens

Ein persönliches Zugriffstoken (Personal Access Token, PAT) ist eine Anmeldeinformation, die Sie selbst erstellen und einfügen. Es ist für die Waafir-REST-API und Skripte gedacht sowie für einen KI-Assistenten, der sich nicht anmelden kann: Die meisten Assistenten verbinden sich, indem Sie die Waafir-URL einfügen und sich anmelden, ganz ohne Token. Auf den MCP-Servern von Waafir trägt jede Anfrage entweder eine per Anmeldung hergestellte Verbindung oder ein gültiges PAT. Es gibt keinen anonymen Zugriff, und eine gewöhnliche angemeldete Browsersitzung wird auf dieser Oberfläche nicht akzeptiert (eine per Sitzung authentifizierte Anfrage wird abgelehnt). Ein PAT handelt als Sie, innerhalb Ihrer Organisation, begrenzt durch den Bereich und die Datenräume, die Sie beim Ausstellen wählen.

Wo Sie ein Token ausstellen

Öffnen Sie Add-ons → Konfiguration → API-Token. Die Seite hat drei Teile: ein Formular zum Ausstellen eines neuen Tokens, die Liste Ihrer vorhandenen Tokens (mit einer Widerrufsaktion) und ein sofort nutzbares Konfigurations-Snippet, um einen Assistenten mit einem Token zu verbinden.

Um ein Token auszustellen, füllen Sie das Formular aus:

  • Name — eine für Menschen lesbare Bezeichnung, damit Sie das Token später wiedererkennen (zum Beispiel „Claude Desktop – Laptop“). Pflichtfeld.
  • Bereich — was das Token tun darf. Siehe unten.
  • Datenraum-Bereich — lassen Sie Alle Datenräume aktiviert, damit das Token jeden Datenraum erreicht, auf den Sie zugreifen können, oder deaktivieren Sie es und wählen Sie bestimmte Datenräume aus, um das Token auf genau diese zu beschränken.
  • Ablauf — das Datum, nach dem das Token nicht mehr funktioniert. Das Ausfüllen ist optional, die Wirkung aber nicht optional: Lassen Sie es leer, wird das Token mit einem Ablauf von 90 Tagen ausgestellt. Siehe Ablauf.

Bereiche (Scopes)

Ein Token trägt einen von drei Bereichen, in aufsteigender Reihenfolge der Befugnisse:

BereichErlaubtTypische Verwendung
readAuflisten und Lesen — Datenräume, Ordner, Dateien, Dateimetadaten, Suche, Download-URLs und das Anzeigen von Berechtigungen; das Lesen des extrahierten Texts eines Dokuments; das Lesen von Q&A-Threads der Investoren; das Prüfen des Status eines Schwärzungs-, Übersetzungs- oder E-Signatur-Auftrags.Ein schreibgeschützter Assistent, der Fragen zu einem Datenraum beantwortet.
writeAlles, was read erlaubt, plus Änderungen: Ordner erstellen, umbenennen, verschieben, löschen und wiederherstellen; Dateien hochladen, umbenennen, verschieben, löschen und wiederherstellen, einschließlich des Hochladens einer neuen Version einer Datei und des Zurücksetzens auf eine frühere; eine Schwärzung oder Übersetzung eines Dokuments starten; sowie E-Signatur-Umschläge erstellen, senden, ablehnen und ungültig machen. Das Senden eines Umschlags (oder das Hinzufügen von Unterzeichnern zu einem bereits gesendeten) erfordert außerdem An Personen außerhalb Ihrer Organisation senden, und Ihr Assistent bittet Sie vor dem Senden um Bestätigung. Das Signieren (esign_sign) erfordert außerdem Dokumente signieren und wird ebenfalls zuvor bestätigt.Ein Assistent, der einen Datenraum organisiert oder pflegt.
adminAlles, was write erlaubt, plus die vier Tools zum Erteilen von Berechtigungen: Zugriff eines Benutzers auf Dateien und Datenräume gewähren oder widerrufen. Beachten Sie, dass die drei Tools zum Lesen von Berechtigungen nur read benötigen.Ein Assistent, der verwaltet, wer was sehen kann.

Bereiche sind kumulativ — ein höherer Bereich umfasst alles darunter. Die Tool-Referenz jedes Servers gibt den Mindestbereich an, den jedes Tool benötigt.

Wer welchen Bereich ausstellen kann

Ein Token kann nie mehr Befugnisse tragen als die Person, die es ausstellt:

  • read und write können von jedem aktiven Mitglied Ihrer Organisation ausgestellt werden.
  • admin kann nur von einem Eigentümer oder Admin der Organisation ausgestellt werden. Wenn Sie weder Eigentümer noch Admin sind, erscheint die Option admin in der Bereichsauswahl nicht.
  • Investoren (und andere Rollen außerhalb des Deal-Teams) können überhaupt keine Tokens ausstellen.

Über die Ausstellung hinaus wenden die admin-Berechtigungstools beim Aufruf eine zweite Obergrenze an: Der Inhaber des Tokens muss selbst Admin oder Manager in der Organisation sein, damit eine Berechtigungserteilung gelingt. Der Bereich eines Tokens ist die Obergrenze des Tokens; die Rolle des Inhabers ist die Obergrenze der Person, und eine Admin-Aktion muss beide erfüllen — genau die Regel, die auch die Produktoberfläche anwendet. Über MCP gibt es keinen lockereren Weg als über das Produkt.

Einem Token das Signieren von Dokumenten erlauben

Zum Signieren ist ein Token mit aktiviertem Dokumente signieren erforderlich. Sie wählen dies beim Erstellen des Tokens unter Add-ons → Konfiguration, für ein write- oder admin-Token, sodass nur ein Assistent, dem Sie vertrauen, für Sie signieren kann. Das Erstellen eines Tokens fragt bereits nach Ihrem Zwei-Faktor-Code, wenn Sie die Zwei-Faktor-Authentifizierung aktiviert haben, sodass diese Prüfung jede Signatur abdeckt, die das Token leistet. Die Token-Liste zeigt bei jedem solchen Token Kann signieren an.

Ihr Assistent zeigt Ihnen zuerst die Dokumente, den Unterzeichner und die Felder und signiert erst, wenn Sie bestätigen. Einem Token ohne Dokumente signieren wird esign_sign in seiner Tool-Liste nicht angezeigt, und es wird abgelehnt, wenn es das Tool aufruft. Tokens, die vor Einführung dieser Option erstellt wurden, können nicht signieren: Erstellen Sie ein neues mit aktiviertem Dokumente signieren.

Einem Token das Lesen von Dokumentinhalten erlauben

Ein Dokument vollständig zu lesen oder die KI zu Dokumenten zu befragen, erfordert ein Token mit aktiviertem Dokumentinhalt lesen. Sie wählen dies beim Erstellen des Tokens unter Add-ons → Konfiguration, bei jedem Bereich. Die Token-Liste zeigt bei jedem solchen Token Dokumentinhalt an. Es umfasst:

  • get_file_text, den vollständigen extrahierten Text eines Dokuments;
  • get_file_download_url, einen Link zum Herunterladen einer Datei;
  • esign_download_signed, ein signiertes E-Signatur-PDF;
  • den Download-Link, den translate_file_status für eine fertige Übersetzung zurückgibt;
  • GET /api/v1/files/{fileId}/content, die Bytes des Dokuments über die REST-API;
  • POST /api/viewer/token, POST /api/viewer/artifact-access und POST /api/viewer/artifact-access/unlock, die das Viewer-Token bzw. das Cookie erzeugen, mit dem der Dokumentbetrachter im Produkt ein Dokument streamt;
  • die KI-Tools, deren Frage oder Eingabe Sie verfassen, da eine Antwort wiedergeben kann, was in einem Dokument steht: dataroom_ask, dataroom_draft_answer, dataroom_compare_files und dataroom_generate_update;
  • POST /api/v1/chat, dieselbe KI-Antwort über die REST-API;
  • das quote jedes Fakts, den GET /api/v1/facts zurückgibt.

Einem Token ohne diese Option werden diese Tools (GRANT_REQUIRED) und diese REST-Routen (PAT_GRANT_REQUIRED) verweigert, und translate_file_status gibt den Status mit download_withheld_reason: content_grant_required statt eines Links zurück. GET /api/v1/facts und dataroom_list_facts geben jeden Fakt ohne sein quote zurück, wobei value auf 20 Wörter gekürzt und value_truncated gesetzt ist. Das Token kann weiterhin auflisten und suchen und die Zusammenfassung eines Dokuments mit get_file_metadata oder dataroom_summarise_file lesen. Tokens, die vor Einführung dieser Option erstellt wurden, können keine Dokumentinhalte lesen: Erstellen Sie ein neues mit aktiviertem Dokumentinhalt lesen. Service-Tokens sind nicht betroffen.

Jedes Token kann höchstens 10 Download-Links pro Minute abrufen. Darüber hinaus wird get_file_download_url abgelehnt (RATE_LIMITED), und translate_file_status gibt den Status mit download_withheld_reason: rate_limited zurück; fragen Sie nach einer Minute erneut.

Einem Token das Senden an Personen außerhalb Ihrer Organisation erlauben

Einen Freigabe-Link erstellen, einen Snapshot-Betrachter hinzufügen, ein Teammitglied oder einen Investor einladen sowie den Zugriff eines Investors verlängern oder wiederherstellen (dataroom_extend_investor_access, dataroom_reinstate_investor_access) — all dies gibt jemandem außerhalb Ihrer Organisation Zugriff, daher ist ein Token mit aktiviertem An Personen außerhalb Ihrer Organisation senden erforderlich (dieselbe Berechtigung, mit der Investor-Updates, Q&A-Antworten und E-Signatur-Anfragen gesendet werden). Sie wählen dies beim Erstellen eines write- oder admin-Tokens unter Add-ons → Konfiguration. Die Token-Liste zeigt bei jedem solchen Token Kann extern versenden an.

Ihr Assistent zeigt Ihnen zuerst, wen ein neuer Link zulässt, die NDA-Regel und den Ablauf, und erstellt ihn erst, wenn Sie bestätigen. Das Widerrufen eines Links oder eines Betrachters erfordert keine Berechtigung.

Die Berechtigung umfasst außerdem, jemandem außerhalb Ihres Deal-Teams (Eigentümer, Admins und Mitglieder) Zugriff oder mehr Zugriff auf einen Raum oder ein Dokument zu geben. „Außerhalb“ bedeutet jede Person, die kein aktives Deal-Team-Mitglied der Organisation des Raums ist: Investoren, Gäste, Personen mit einer ausstehenden Einladung und Mitglieder einer anderen Organisation. Ohne die Berechtigung wird ein Token abgelehnt (GRANT_REQUIRED auf MCP) bei:

  • einer Lese- oder Download-Berechtigung für eine solche Person: set_file_permissions, dataroom_set_folder_permissions, dataroom_bulk_set_file_permissions;
  • dem Entfernen einer Sperre (Deny) für eine solche Person, wodurch ihr Zugriff wiederhergestellt wird: revoke_file_permission, dataroom_revoke_folder_permission, dataroom_bulk_revoke_file_permissions;
  • Raumzugriff für eine solche Person, auf jeder Stufe: invite_user_to_dataroom;
  • dem Ändern der Rolle eines Mitglieds, dessen aktuelle Rolle nicht zum Deal-Team gehört, was es befördert: dataroom_team_change_member_role;
  • einer Investor-Änderung, die den Zugriff erweitert: dataroom_set_investor_permissions von Betrachter zu Downloader, das Deaktivieren des NDA oder das Aktivieren von Monitoring oder Updates.

Sperren, das Beenden einer Berechtigung und Berechtigungen für Ihr Deal-Team erfordern keine Berechtigung. Inhalte, die dort abgelegt werden, wo eine Person bereits Zugriff hat (Hochladen, Verschieben, Veröffentlichen), sind nicht erfasst. Das Anhängen eines Firmen-NDA, das die Firma unterzeichnet hat, erfordert keine Berechtigung.

Dieselbe Berechtigung gilt für diese REST-Aufrufe, die mit einem persönlichen Zugriffstoken erfolgen:

  • POST /api/share-links (einen Link erstellen) und POST /api/snapshots/{id}/viewers werden ohne sie mit 403 PAT_GRANT_REQUIRED abgelehnt;
  • POST /api/investors/invite (erstellt einen persönlichen Link und versendet ihn per E-Mail) wird auf dieselbe Weise abgelehnt;
  • PATCH /api/investors/{id}/extend und PATCH /api/investors/{id}/access (einen Investor wiederherstellen oder eine Zugriffsanfrage genehmigen) werden auf dieselbe Weise abgelehnt; das Widerrufen eines Investors (DELETE /api/investors/{id}/access) erfordert keine Berechtigung;
  • POST /api/team, POST /api/v1/team und POST /api/team/resend (eine Team-Einladung versendet einen Beitrittslink per E-Mail) werden auf dieselbe Weise abgelehnt;
  • PATCH /api/share-links/{id} wird bei jeder Änderung der Zugriffseinstellungen eines Links abgelehnt (Aktivieren, Modus, Domains, Ablauf oder NDA, ob die Änderung sie erweitert oder verschärft); das Deaktivieren eines Links ist immer erlaubt;
  • GET /api/share-links antwortet ohne url und token jedes Links, gekennzeichnet mit urlWithheld: true, und mit einem urlWithheldReason, der den Grund nennt;
  • POST /api/v1/grants wird bei einer Lese- oder Download-Berechtigung für jemanden außerhalb des Deal-Teams abgelehnt; DELETE /api/v1/grants/{id} wird abgelehnt, wenn die Berechtigung die Sperre dieser Person ist; PATCH /api/v1/team/{id} wird abgelehnt, wenn die aktuelle Rolle des Mitglieds nicht zum Deal-Team gehört.

Diese Prüfungen lesen den Pfad so, wie der Server ihn routet, sodass ein abschließender Schrägstrich oder ein prozentkodiertes Zeichen sie nicht umgeht. Ein Pfad, der nicht dekodiert werden kann oder ein ./..-Segment oder einen kodierten / innerhalb eines Segments enthält, kann keinem der Aufrufe zugeordnet werden, die eine Berechtigung abdeckt. Daher werden bei einem persönlichen Zugriffstoken, dem irgendeine Berechtigung pro Anfrage fehlt — diese, Dokumentinhalt lesen oder Engagement-Analysen lesen —, alle solchen Pfade mit 403 PAT_PATH_MALFORMED abgelehnt, unabhängig vom Aufruf.

Tokens, die vor Einführung dieser Berechtigung erstellt wurden, besitzen sie nicht und verlieren daher diese Aufrufe, bis Sie ein neues write- oder admin-Token mit aktivierter Option erstellen. Ein read-Token kann die Berechtigung nicht besitzen.

Einem Token das Lesen von Engagement-Analysen erlauben

Engagement-Analysen lesen erlaubt einem Token zu lesen, wer welche Dokumente wann und wie lange angesehen hat: die Engagement-Tools und die Engagement-Fakten in der Investorenliste. Aktivieren Sie dies nur für einen Assistenten, der das sehen soll. Jeder Bereich kann diese Berechtigung besitzen.

Dieselbe Berechtigung gilt für die REST-Aktivitätsabfragen: GET /api/v1/activity (der Aktivitäts- und Audit-Feed der Organisation), /api/v1/activity/rollups, /api/v1/activity/engagement, /api/v1/activity/engagement/documents und /api/v1/activity/engagement/document/pages. Ohne sie wird ein persönliches Zugriffstoken mit 403 PAT_GRANT_REQUIRED abgelehnt. Service-Tokens und angemeldete Sitzungen sind nicht betroffen.

Tokens, die vor Einführung dieser Optionen erstellt wurden, besitzen keine von beiden: Erstellen Sie ein neues mit aktivierter Option.

Ein Token auf bestimmte Datenräume beschränken

Standardmäßig kann ein Token jeden Datenraum erreichen, auf den sein Inhaber zugreifen kann. Wenn Sie Alle Datenräume deaktivieren und bestimmte Räume auswählen, wird das Token auf diese Allowlist beschränkt: Jeder Tool-Aufruf, der einen Datenraum außerhalb der Liste betrifft, wird abgelehnt, und ein beschränktes Token sieht nicht einmal die Namen von Datenräumen, die es nicht öffnen kann. Nutzen Sie dies, um einem KI-Client Zugriff auf einen Deal zu geben, ohne den Rest Ihres Portfolios offenzulegen.

Ablauf

Jedes Token läuft ab. Es gibt kein unbefristetes PAT: Ein Token, das nie ablief, war selbst der Sicherheitsbefund, den dieses Verhalten beheben soll, denn eine vergessene Anmeldeinformation bleibt sonst für immer gültig. Wenn Sie ein Ablaufdatum festlegen, funktioniert das Token nach diesem Datum nicht mehr — eine Anfrage mit einem abgelaufenen Token wird genau wie eine mit einem widerrufenen abgelehnt, mit HTTP 401.

  • Lassen Sie das Feld leer, erhalten Sie 90 Tage, gerechnet ab dem Moment der Ausstellung des Tokens. Leer bedeutet Standard verwenden, nicht nie ablaufen.
  • Legen Sie ein Datum fest, wird es exakt eingehalten, bis zu einer Obergrenze von 365 Tagen ab Ausstellung.
  • Fordern Sie mehr als 365 Tage an, wird die Anfrage abgelehnt, nicht stillschweigend verkürzt — die Ausstellung gibt Ihnen nie ohne Hinweis ein kürzer gültiges Token zurück, als Sie angefordert haben. Ein Datum in der Vergangenheit wird auf dieselbe Weise abgelehnt.

Wenn eine Integration also dauerhaft laufen soll, legen Sie den Ablauf bewusst fest und tragen Sie sich eine Erinnerung in den Kalender ein, das Token vor dem Ablauf zu ersetzen — ein leeres Feld lässt diese Integration etwa drei Monate nach der Einrichtung stillschweigend ausfallen. Es gibt keine Verlängerungs- oder Rotationsaktion für ein bestehendes Token und keine Warnung vor dem Ablauf: Ein Token zu ersetzen bedeutet, ein neues auszustellen, die Konfiguration Ihres Clients zu aktualisieren und das alte zu widerrufen. Umgekehrt ist ein kurzer Ablauf genau richtig für ein Token, das Sie für eine einmalige Aufgabe ausstellen.

Die Token-Liste unter Add-ons → Konfiguration zeigt den Ablauf jedes Tokens, sodass Sie sehen, was demnächst abläuft.

Die einmalige Anzeige

Wenn Sie ein Token ausstellen, wird der Rohwert — er beginnt mit waafir_pat_ — genau einmal angezeigt, unmittelbar nach der Erstellung. Waafir speichert das Roh-Token nie, nur einen Einweg-Hash davon, sodass es nicht erneut abgerufen oder angezeigt werden kann.

  • Kopieren Sie es sofort und fügen Sie es direkt in die Konfiguration Ihres Clients ein. Das Anzeigefenster hat eine Kopierschaltfläche.
  • Wenn Sie es verlieren, können Sie es nicht wiederherstellen — widerrufen Sie dieses Token und stellen Sie ein neues aus.
  • Behandeln Sie es wie ein Passwort: Es gewährt jedem, der es besitzt, seinen Bereich.

Nach der Anzeige zeigt die Token-Liste nur noch ein kurzes, nicht geheimes Präfix (zum Beispiel waafir_pat_ab12…), damit Sie Ihre Tokens unterscheiden können, ohne dass das Geheimnis wiederherstellbar ist.

Ein Token widerrufen

Verwenden Sie in der Token-Liste unter Add-ons → Konfiguration die Aktion Widerrufen neben einem beliebigen Token. Der Widerruf wirkt sofort — die nächste Anfrage mit dem Token wird abgelehnt. Widerrufen Sie ein Token, sobald ein Gerät verloren geht, ein externer Mitarbeiter ausscheidet oder Sie den Zugriff schlicht nicht mehr benötigen. Widerrufene Tokens bleiben in der Liste sichtbar (als widerrufen gekennzeichnet), damit dokumentiert bleibt, was existierte; sie können nie wieder aktiviert werden.

Wenn ein Token von selbst endet

Ein Token handelt über Ihre Mitgliedschaft in der Organisation und endet daher mit dieser Mitgliedschaft. Sie müssen es nicht selbst widerrufen, wenn:

  • Sie die Organisation verlassen oder ein Admin Sie entfernt. Jedes Token, das Sie in dieser Organisation besitzen, wird in diesem Moment widerrufen. Tokens, die Sie in anderen Organisationen besitzen, funktionieren weiter.
  • Ein Waafir-Administrator Ihr Konto löscht. Ihre Tokens in jeder Organisation werden widerrufen.
  • Ein Waafir-Administrator die Organisation löscht. Jedes Token darin wird widerrufen, einschließlich ihrer Service-Tokens.

Diese Widerrufe sind endgültig. Eine erneute Einladung oder die Wiederherstellung Ihres Kontos oder der Organisation bringt ein Token nicht zurück: Stellen Sie ein neues aus.

Ein Service-Token gehört der Organisation, nicht dem Admin, der es erstellt hat, und funktioniert daher weiter, wenn dieser Admin ausscheidet. Nur sein Widerruf oder das Löschen der Organisation beendet es vorzeitig.

Der Token-Verlauf im Audit-Log

Jedes ausgestellte oder widerrufene Token schreibt eine Zeile in das Audit-Log der Organisation: wer es getan hat, der Name, Bereich, die Berechtigungen und der Ablauf des Tokens, auf wie viele Datenräume es beschränkt ist und warum es widerrufen wurde (durch seinen Inhaber, weil eine Mitgliedschaft endete oder weil ein Konto oder eine Organisation gelöscht wurde). Das Token selbst, sein Hash und sein Präfix werden nie erfasst. Die Zeilen erscheinen im vollständigen Aktivitätsverlauf, nicht in der Dashboard-Übersicht.

Kann Waafir ein neues Token nicht im Audit-Log erfassen, wird das Token nicht ausgestellt, und Sie sehen „The token wasn't created because we couldn't record it. Try again.“

Weiter: Richten Sie Ihren Client mit dem gerade ausgestellten Token ein.