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:
| Situation | Ergebnis |
|---|---|
| Ein beschränkter Typ, den Sie nicht lesen dürfen, auf Wurzelebene | data ist null, da Wurzel-Connections non-null sind; errors[] bezeichnet das Feld |
| Ein beschränkter Typ über eine To-one-Relation erreicht | Das Relationsfeld ist null; errors[] bezeichnet dieses Feld |
| Ein beschränkter Typ über eine To-many-Relation erreicht | Das Relationsfeld ist null; errors[] bezeichnet dieses Feld |
| Ein Typ, der nur als Kind eines anderen Datensatzes existiert | Nie 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:
| Status | Bedeutung |
|---|---|
401 | Kein 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.