Authentifizierung
Jede /v1-Anfrage wird authentifiziert. Aus Ihren eigenen Systemen
authentifizieren Sie sich mit einem persönlichen Zugriffstoken (PAT), das als
Bearer-Token gesendet wird:
Authorization: Bearer waafir_pat_…Tokens stellen Sie unter Add-ons → Konfiguration aus, schränken sie ein und widerrufen sie. Der Leitfaden zu persönlichen Zugriffstokens behandelt Ausstellung, Ablauf (standardmäßig 90 Tage, höchstens 365), die einmalige Anzeige und den Widerruf. Diese Regeln gelten für die Plattform-API gleichermaßen. Diese Seite behandelt, was ein Token kann, sobald Sie eines besitzen.
Ein persönliches Zugriffstoken handelt als die Person, die es ausgestellt hat, innerhalb der Organisation dieser Person. In keiner URL und keinem Body gibt es einen Organisationsparameter, weil das Token die Organisation bereits festlegt.
Die drei Token-Prüfungen
Eine per Token authentifizierte Anfrage muss unter anderem diese drei Prüfungen
bestehen. Auch die Sicherheitsrichtlinie der Organisation und die eigenen
Prüfungen des Endpunkts können sie ablehnen
(siehe unten). Zwei der drei haben einen eigenen Code. Eine
Ablehnung aufgrund der Rolle kann mit FORBIDDEN antworten, das auch andere
Ablehnungen verwenden; lesen Sie den Code daher zusammen mit den Anforderungen
des Endpunkts.
| Prüfung | Frage | Ablehnung |
|---|---|---|
| Token-Scope | Deckt der Scope des Tokens ab, was dieser Endpunkt tut? | PAT_SCOPE_INSUFFICIENT 403 |
| Rolle | Hat der Aufrufer die Rolle, die dieser Endpunkt verlangt? | FORBIDDEN 403 oder PAT_ROLE_CEILING 403 |
| Datenraum | Steht dieser Datenraum bei einem auf Datenräume beschränkten Token auf dessen Liste? | PAT_DATAROOM_SCOPE 403 |
Token-Scopes
Ein Token hat genau einen Scope: read, write oder admin, in aufsteigender
Reihenfolge der Befugnisse. Ein höherer Scope umfasst alles darunter.
Welchen Scope ein Endpunkt benötigt, richtet sich standardmäßig nach seiner HTTP-Methode:
GET,HEADundOPTIONSbenötigenread.- Jede andere Methode (
POST,PATCH,PUT,DELETE) benötigtwrite.
Manche Endpunkte deklarieren einen anderen Scope. Der übliche Fall ist ein
POST, der nur eine Abfrage ausführt und daher nur read benötigt. Die
Endpunkt-Referenz zeigt den Scope, den jeder
Endpunkt tatsächlich verlangt; prüfen Sie ihn dort, statt ihn aus der Methode
abzuleiten.
Erforderliche Rolle und Rollenobergrenze
Der Scope legt fest, was das Token darf. Die erforderliche Rolle des
Endpunkts legt fest, wer die Person sein muss. Viele /v1-Endpunkte
verlangen das Deal-Team (einen Eigentümer, Administrator oder ein Mitglied der
Organisation). Änderungen am Team und an Zugriffsfreigaben erfordern unter
anderem einen Eigentümer oder Administrator. Investoren und andere Gäste haben
keine Deal-Team-Rolle, daher lehnen Deal-Team-Endpunkte sie ab. Andere Endpunkte
deklarieren auf der Authentifizierungsebene keine Rollenbeschränkung und prüfen
den Zugriff stattdessen innerhalb des Endpunkts. So prüfen etwa die Routen der
Portfolio-Überwachung das Überwachungs-Add-on und den Überwachungszugriff des
Aufrufers. Die Endpunkt-Referenz zeigt die
Rollenbeschränkung jedes Endpunkts. Wo keine deklariert ist, kann der Endpunkt
die Anfrage trotzdem selbst ablehnen.
Ein Token speichert außerdem die Rolle seines Ausstellers zum Zeitpunkt der Ausstellung als Obergrenze. Waafir wendet die niedrigere von aktueller Rolle
des Ausstellers und dieser Obergrenze an. Ein Mitglied, das später zum
Administrator befördert wird, handelt über ein früher ausgestelltes Token
weiterhin als Mitglied; stellen Sie ein neues Token aus, um die neue Rolle zu
nutzen. Eine Person, deren Rolle herabgestuft wird, verliert die Befugnis sofort,
unabhängig davon, was das Token gespeichert hat. Beide Defizite werden mit 403
abgelehnt, als FORBIDDEN oder PAT_ROLE_CEILING.
Auf Datenräume beschränkte Tokens
Ein Token, das mit ausgewählten Datenräumen statt mit Alle Datenräume
ausgestellt wurde, erreicht nur diese Räume. Eine Anfrage, die einen anderen
Datenraum nennt, wird mit PAT_DATAROOM_SCOPE abgelehnt. Manche
organisationsweiten Endpunkte lehnen ein beschränktes Token grundsätzlich mit
demselben Code ab, weil ihre Antwort Datenräume umfasst, die das Token nicht
sehen kann. Verwenden Sie dafür ein unbeschränktes Token.
GET /api/v1/session akzeptiert beide Arten.
Weitere Ablehnungen, denen Sie begegnen können
401 UNAUTHORIZED: keinAuthorization-Header oder ein Token, das unbekannt, abgelaufen oder widerrufen ist.404für eine Ressource einer anderen Organisation. Eine ID, die zu einer anderen Organisation gehört, wird als nicht gefunden behandelt, sodass ihre Existenz nicht bestätigt wird.- Keine Überschreibung durch Eigentümer/Administrator bei eingeschränkten Dateien. In der App sieht ein Eigentümer oder Administrator der Organisation
jede eingeschränkte Datei. Ein Token nicht: Es erreicht eine eingeschränkte
Datei nur, wenn sein Inhaber sie erstellt hat oder eine Freigabe dafür hat.
Eine Anfrage, die eine Datei nennt, die es nicht lesen kann, erhält dieselbe
Antwort wie für eine fehlende Datei (bei
/api/v1/grantsein400, das die Datei nennt, oder ein404für die Freigabe), mit der Meldung, sie sei „not found, or not readable by this credential“, sodass die Antwort die Existenz der Datei nie bestätigt. - Sicherheitsrichtlinie der Organisation. Hat Ihre Organisation eine
IP-Zulassungsliste, beantwortet eine Anfrage von außerhalb sie mit
IP_BLOCKED. Die Durchsetzung der Zwei-Faktor-Authentifizierung kann mitMFA_SETUP_REQUIREDoderMFA_CHALLENGE_REQUIREDantworten. 429 RATE_LIMITED. Manche Endpunkte deklarieren eine Obergrenze pro Minute für jede Identität, die beim Endpunkt angegeben ist. Die übrigen nutzen den Plattform-Standard. Warten Sie und versuchen Sie es erneut.
Die Seite Fehlercodes listet die bekannten Codes mit ihrer Bedeutung auf.