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:
| Bereich | Erlaubt | Typische Verwendung |
|---|---|---|
read | Auflisten 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. |
write | Alles, 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. |
admin | Alles, 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:
readundwritekönnen von jedem aktiven Mitglied Ihrer Organisation ausgestellt werden.adminkann nur von einem Eigentümer oder Admin der Organisation ausgestellt werden. Wenn Sie weder Eigentümer noch Admin sind, erscheint die Optionadminin 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_statusfü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-accessundPOST /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_filesunddataroom_generate_update; POST /api/v1/chat, dieselbe KI-Antwort über die REST-API;- das
quotejedes Fakts, denGET /api/v1/factszurü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_permissionsvon 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) undPOST /api/snapshots/{id}/viewerswerden ohne sie mit403 PAT_GRANT_REQUIREDabgelehnt;POST /api/investors/invite(erstellt einen persönlichen Link und versendet ihn per E-Mail) wird auf dieselbe Weise abgelehnt;PATCH /api/investors/{id}/extendundPATCH /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/teamundPOST /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-linksantwortet ohneurlundtokenjedes Links, gekennzeichnet miturlWithheld: true, und mit einemurlWithheldReason, der den Grund nennt;POST /api/v1/grantswird 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.