Zum Hauptinhalt springen

Authentifizierung und Berechtigungen

GraphQL verwendet dasselbe Authentifizierungsmodell wie REST. Senden Sie an beide Endpoints ein OAuth2/OIDC-Access-Token als Bearer-Token:

curl -X POST "https://api.tourfold.com/api/v2/graphql" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"{ equipment(first: 1) { edges { node { id created_at } } } }"}'

Ersetzen Sie equipment durch einen Definitions-Slug aus Ihrem eigenen Workspace, und beachten Sie die Form: Eine Connection muss über edges { node { … } } selektiert werden, und die Seitengröße steuert first — ein limit-Argument gibt es nicht.

Verwenden Sie den Authorization-Code-Flow für Anwendungen mit Benutzeroberfläche und Client Credentials für Server-zu-Server-Integrationen. Flows, Endpoints und Token-Laufzeiten sind einmal für beide Oberflächen unter REST-Authentifizierung dokumentiert.

Berechtigungen je Ressource​

Aufgaben benötigen tasks:read, Touren (system_tour) tours:read oder tours:read:own (beschränkt auf veröffentlichte Touren, an denen der Aufrufer teilnimmt; zusätzlich tasks:read beim Auflösen von task_visit-Stopps, tasks oder task_assignments), Fahrzeuge vehicles:read, Skills skills:read, Benutzer users:read und Geräte devices:read. Objektberechtigungen ersetzen keine dieser Freigaben. Die Prüfung gilt für Wurzelfelder, Beziehungen, Referenzfilter und Sortierungen, auch wenn keine Datensätze passen. Ausdrücklich erlaubter Zugriff über ein Elternobjekt bleibt erhalten. Verweigerter Datensatzzugriff erscheint als GraphQL-Feldfehler bei HTTP 200; fehlende Anmeldung wird mit HTTP 401 abgewiesen.

Schema und Datensätze​

Beide Endpoints erfordern eine Anmeldung. Zum Herunterladen des Schemas ist kein Datensatz-Leserecht nötig. Für benutzerdefinierte Objektdatensätze gelten objects:records:read und die Zugriffsregeln der Definition; für native Ressourcen gilt das Leserecht der jeweiligen Funktion. Schreibrechte werden separat an der nativen REST-API geprüft.

Zugriff je Typ​

Zusätzlich zum Objekt-Leserecht können einzelne Objekttypen zugriffsbeschränkt sein. Die Objektmetadaten sind für den Tenant sichtbar und stabil: Alle Typen bleiben im generierten Schema. Datensätze werden pro Typ zur Ausführungszeit geprüft; verweigerte Felder erzeugen ausdrückliche GraphQL-Fehler:

SituationErgebnis
Ein beschränkter Typ, den Sie nicht lesen dürfen, auf Wurzelebenedata ist null, da Wurzel-Connections non-null sind; errors[] bezeichnet das Feld
Ein beschränkter Typ über eine To-one-Relation erreichtDas Relationsfeld ist null; errors[] bezeichnet dieses Feld
Ein beschränkter Typ über eine To-many-Relation erreichtDas Relationsfeld ist null; errors[] bezeichnet dieses Feld
Ein Typ, der nur als Kind eines anderen Datensatzes existiertNie auf Wurzelebene verfügbar, nur über den Elterndatensatz

Soweit die GraphQL-Nullbarkeit es zulässt, bleiben lesbare Geschwisterfelder in data erhalten. Ein Zugriffsfehler hat den stabilen Wert extensions.code = "https://problems.tourfold.com/access-denied" und extensions.data = {"reason":"not_member","type":"object:<slug>"}. Clients können damit eine leere Sammlung sicher von einem verweigerten Zugriff unterscheiden, ohne Meldungstexte auszuwerten.

Schreibgeschützte integrierte Objektdefinitionen haben keine bearbeitbare Berechtigungsmatrix pro Objekt. Ihre Datensätze werden anhand der Berechtigung ihrer zuständigen Funktion gelesen. Schreibvorgänge laufen weiterhin über die native REST-API der jeweiligen Ressource.

Authentifizierungsfehler sind HTTP-Fehler, keine GraphQL-Fehler​

Die Authentifizierung wird geprüft, bevor die GraphQL-Engine läuft. Sie erscheinen daher als HTTP-Statuscodes mit einem Problemdokument nach RFC 9457 — nicht als Einträge in einem GraphQL-errors-Array:

StatusBedeutung
401Kein Token, ein abgelaufenes Token oder ein ungültiges Token.

Fehlende Leserechte erzeugen bei HTTP 200 einen Feldfehler mit extensions.data.reason = "missing_grant" und required_grants. Siehe Fehler und Limits.

Praktische Hinweise​

  • Tokens gelten für einen Workspace. Verwenden Sie ein Token, das für den Workspace ausgestellt ist, dessen Daten Sie abfragen.
  • Bevorzugen Sie in Anwendungen mit Benutzeroberfläche kurzlebige Access-Tokens mit Refresh-Tokens; binden Sie niemals ein langlebiges Token in eine Client-Anwendung ein.
  • Die GraphQL-API ist ausschließlich lesend. Ein nur zum Abfragen genutztes Token benötigt daher nur die passenden Leserechte der abgefragten Ressourcen; diese erlauben keine REST-Schreibvorgänge.