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

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üfungFrageAblehnung
Token-ScopeDeckt der Scope des Tokens ab, was dieser Endpunkt tut?PAT_SCOPE_INSUFFICIENT 403
RolleHat der Aufrufer die Rolle, die dieser Endpunkt verlangt?FORBIDDEN 403 oder PAT_ROLE_CEILING 403
DatenraumSteht 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, HEAD und OPTIONS benötigen read.
  • Jede andere Methode (POST, PATCH, PUT, DELETE) benötigt write.

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: kein Authorization-Header oder ein Token, das unbekannt, abgelaufen oder widerrufen ist.
  • 404 fü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/grants ein 400, das die Datei nennt, oder ein 404 fü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 mit MFA_SETUP_REQUIRED oder MFA_CHALLENGE_REQUIRED antworten.
  • 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.