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.

Lesen erfordert ein Schreibrecht

warnung

Für Abfragen über die GraphQL-API wird eines der Schreibrechte auf Custom Objects benötigt:

• custom-objects:instances:create
• custom-objects:instances:update
• custom-objects:instances:delete

Ein Recht custom-objects:instances:read existiert nicht, und die Berechtigungsprüfung findet einmalig am Endpoint statt. Eine Rolle mit ausschließlich lesendem Zugriff auf Custom Objects kann die GraphQL-API daher überhaupt nicht nutzen — weder den Abfrage- noch den Schema-Endpoint.

Wenn Sie heute eine rein lesende Integration benötigen, geben Sie ihr entweder eines der oben genannten Schreibrechte — und nehmen in Kauf, dass damit auch Schreibvorgänge über REST möglich sind — oder nutzen Sie die REST-Endpoints für Custom Objects, die eine Berechtigungsprüfung auf Leseebene haben. Ein eigenes Leserecht ist geplant; bis es ausgeliefert ist, ist dies die tatsächliche Anforderung und nicht eine schönere.

Beide Endpoints sind identisch geschützt: Ein Token, das nicht abfragen darf, kann auch das Schema nicht herunterladen.

Zugriff je Typ

Über das Recht am Endpoint hinaus können einzelne Custom-Object-Typen zugriffsbeschränkt sein. Diese Prüfungen laufen pro Typ zur Ausführungszeit, und sie lassen die Abfrage nicht scheitern:

Situation	Ergebnis
Ein beschränkter Typ, den Sie nicht lesen dürfen, auf Wurzelebene	Eine leere Connection (edges: [], totalCount: 0)
Ein beschränkter Typ über eine To-one-Relation erreicht	null
Ein beschränkter Typ über eine To-many-Relation erreicht	Eine leere Connection
Ein Typ, der nur als Kind eines anderen Datensatzes existiert	Nie auf Wurzelebene verfügbar, nur über den Elterndatensatz

Der Rest der Abfrage wird weiterhin ausgeführt und liefert weiterhin Daten. Damit lässt ein einzelner unzugänglicher Zweig eine im Übrigen gültige Anfrage nicht scheitern — das hat aber eine wichtige Konsequenz: Ein leeres Ergebnis ist kein Beweis für eine leere Sammlung. Kommt ein Typ, von dem Sie wissen, dass er gefüllt ist, leer zurück, prüfen Sie die Rechte der Rolle an diesem Typ, bevor Sie auf fehlende Datensätze schließen.

Authentifizierungsfehler sind HTTP-Fehler, keine GraphQL-Fehler

Authentifizierung und Autorisierung werden 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.
403	Ein gültiges Token, dessen Rolle kein Schreibrecht auf Custom Objects hat. Der Body nennt die Rechte, die die Prüfung erfüllt hätten.

Eine 200-Antwort mit errors im Body ist deshalb nie ein Authentifizierungsproblem, sondern betrifft die Abfrage selbst. 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 braucht also keine Rechte über das hinaus, das den Endpoint freischaltet — beachten Sie aber, dass dieses Recht auch Schreibvorgänge über REST erlaubt.