Zum Hauptinhalt springen

Authentifizierung

Die REST-API authentifiziert jede Anfrage mit einem OAuth2-/OIDC-Access-Token (einem Bearer-JWT), das von unserem Identity-Provider (Keycloak) ausgestellt wird. Es gibt keine API-Schlüssel: Server-zu-Server-Integrationen authentifizieren sich als Servicekonto mit Client-ID und Secret und erhalten dieselbe Art von Token.

Ein Access-Token verwenden​

Fügen Sie das Token bei jeder Anfrage im Authorization-Header ein:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.tourfold.com/api/v2/areas

Anfragen ohne gültiges Token erhalten 401 Unauthorized — Payload und Retry-Regeln finden Sie unter Fehlerantworten.

Access-Token beziehen​

Token werden vom Keycloak-Realm des Workspace ausgestellt: tourfold-tenants für die meisten Workspaces oder ein dedizierter Realm namens tf-<Workspace-ID>. Die Endpoints des Realms sind hier auffindbar:

https://auth.tourfold.com/realms/tourfold-tenants/.well-known/openid-configuration

Authorization Code Flow (empfohlen für nutzerorientierte Apps)​

  1. Leiten Sie den Benutzer an den Authorization-Endpoint weiter:
https://auth.tourfold.com/realms/tourfold-tenants/protocol/openid-connect/auth
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REDIRECT_URI
&scope=openid profile email
&state=YOUR_STATE_VALUE
  1. Tauschen Sie den Authorization Code gegen Token ein:
curl -X POST https://auth.tourfold.com/realms/tourfold-tenants/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "code=AUTHORIZATION_CODE" \
-d "redirect_uri=YOUR_REDIRECT_URI"

Antwort:

{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 300,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Servicekonten (Server-zu-Server)​

Hintergrund-Jobs und andere Systeme authentifizieren sich als Servicekonto: eine Integrationsidentität, die ihre Grants wie ein Benutzer über ihre Rollen erhält, sich aber nie interaktiv anmeldet. Ein Servicekonto authentifiziert sich mit einer Client-ID und einem Client-Secret (dem Grant client_credentials, RFC 6749 §4.4). Tourfold zeigt das Secret nur einmal an: beim Anlegen des Kontos oder wenn sein Secret erneuert wird.

1. Das Servicekonto anlegen​

Ein Workspace-Administrator legt es unter Einstellungen → Benutzer & Rollen → Servicekonten an oder mit POST /api/v2/service-accounts (erfordert den Grant service-accounts:manage, den nur die Rollen Owner und Admin haben) und übergibt einen Namen, eine optionale Beschreibung und die Rollen. Nur ein menschlicher Benutzer kann ein Servicekonto anlegen, sein Secret erneuern, es aktivieren oder eines seiner Legacy-Token wieder zulassen; ruft ein Servicekonto diese Operationen auf, erhält es 403 mit data.reason: wrong_actor_type, unabhängig von seinen Grants. Eine kompromittierte Integration kann sich daher keine zweite Zugangsberechtigung verschaffen, die ihre Deaktivierung überdauert. Die Antwort enthält alles, was die Integration benötigt:

FeldVerwendung
client_iddie Client-ID (tf-sa-<Servicekonto-ID>)
client_secretdas Client-Secret. Wird nur in dieser Antwort zurückgegeben: Legen Sie es sofort in einem Secrets-Manager ab. Spätere Abfragen des Kontos liefern es nie.
token_endpointwo Token angefordert werden

Übernehmen Sie token_endpoint immer aus der Antwort, statt die URL selbst zusammenzusetzen: Der Realm hängt vom Workspace ab (siehe Enterprise: dedizierter Realm). Siehe die Servicekonto-Operationen in der OpenAPI-Referenz.

2. Ein Token anfordern​

Senden Sie den Grant client_credentials an token_endpoint und authentifizieren Sie sich mit Client-ID und Secret per HTTP Basic (client_secret_basic):

curl -X POST "$TOKEN_ENDPOINT" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials"
import os
import requests # pip install requests

TOKEN_ENDPOINT = "https://auth.tourfold.com/realms/tf-<Workspace-ID>/protocol/openid-connect/token"
CLIENT_ID = "tf-sa-<Servicekonto-ID>"
CLIENT_SECRET = os.environ["TOURFOLD_CLIENT_SECRET"]

def request_token() -> str:
response = requests.post(
TOKEN_ENDPOINT,
auth=(CLIENT_ID, CLIENT_SECRET),
data={"grant_type": "client_credentials"},
)
response.raise_for_status()
return response.json()["access_token"]

client_id und client_secret als Formularfelder zu senden (client_secret_post) funktioniert ebenfalls. Ein falsches oder erneuertes Secret wird mit 401 und "error": "unauthorized_client" abgelehnt. Die meisten OAuth-Bibliotheken unterstützen den Client-Credentials-Grant direkt, zum Beispiel Spring Security, openid-client (Node.js), Authlib (Python) und Duende IdentityModel (.NET).

3. Token verwenden und erneuern​

Ein Access-Token ist 5 Minuten gültig; es gibt kein Refresh-Token. Fordern Sie vor exp ein neues Token an und nach jedem 401 — nicht nur vor exp. Mehrere Änderungen beenden die Token, die ein Servicekonto bereits besitzt (nächster Abschnitt), und ein neues Token behebt alle diese Fälle.

Secret erneuern​

POST /api/v2/service-accounts/{service_account_id}/rotate-secret (oder Secret erneuern in den Einstellungen) gibt ein neues client_secret zurück, einmalig. Das bisherige Secret funktioniert sofort nicht mehr; es gibt keine Übergangszeit, stellen Sie die Integration also direkt nach dem Erneuern um.

Das Erneuern des Secrets, das Deaktivieren oder das Löschen des Kontos beendet innerhalb von 30 Sekunden jedes Token, das vor der Änderung ausgestellt wurde. Rechnen Sie mit einem 401 auf das aktuelle Token und fordern Sie mit dem neuen Secret ein neues an. Ein Token, das in derselben Sekunde wie die Änderung angefordert wird, kann ebenfalls einmal abgelehnt werden; die nächste Anfrage gelingt.

Verlorenes oder kompromittiertes Secret​

Erneuern Sie das Secret oder deaktivieren Sie das Servicekonto (POST /api/v2/service-accounts/{service_account_id}/deactivate). Beides wirkt innerhalb von 30 Sekunden. Das Löschen des Kontos hat dieselbe Wirkung und lässt sich nicht rückgängig machen.

Geräteregistrierung (Pairing-Secret)​

Zwei Geräteregistrierungs-Operationen werden von einem frisch eingerichteten Gerät aufgerufen, das noch keinerlei Token besitzt: POST /api/v2/devices/{device_id}/enroll und POST /api/v2/devices/{device_id}/enroll/challenge. Sie authentifizieren sich mit dem einmaligen Pairing-Secret aus dem Geräte-Einrichtungslink (QR-Code, SMS oder E-Mail) statt mit einem Bearer-Token:

  • das Pairing-Secret wird im Request-Body (secret) übertragen, nie in einem Header oder einer URL;
  • der Workspace wird über den X-Tenant-Id-Header benannt, da ohne Token kein Workspace-Kontext ableitbar ist.

Das Secret ist kurzlebig und an genau ein Gerät gebunden; die Registrierung gelingt höchstens einmal pro Gerät. Nach der Registrierung besitzt das Gerät einen eigenen vertraulichen Client und bezieht Tokens über den Standard-Client-Credentials-Flow (private_key_jwt) — das Pairing-Secret spielt danach keine Rolle mehr. Alle anderen Geräte-Endpunkte verwenden normale Bearer-Authentifizierung.

Für einen deaktivierten Workspace antwortet die Registrierung mit 403 tenant-disabled, für einen wegen der Abrechnung gesperrten mit 402 tenant-billing-locked; die Ablehnung verbraucht den Einrichtungslink nicht, er registriert das Gerät, sobald der Workspace wieder nutzbar ist, solange er nicht abgelaufen ist.

Verliert die App ihren Schlüssel (neu installiert, zurückgesetztes oder ersetztes Gerät), setzt ein Admin die Registrierung mit POST /api/v2/devices/{device_id}/reset-enrollment zurück und sendet einen neuen Einrichtungslink. Das Zurücksetzen meldet die installierte App sofort ab und macht alle davor erzeugten Einrichtungslinks ungültig; das Gerät behält seine ID, seine Fahrzeugverbindung und seinen Verlauf.

Gerätenachweis neben dem Benutzertoken (X-Device-Authorization)​

Bei /api/v2/devices/current bezeichnet current das Gerät, das sich in dieser Anfrage nachweist. Es ist nicht das zuletzt verwendete Gerät des Benutzers. Dieselbe Person kann auf mehreren Geräten unabhängig angemeldet sein.

Senden Sie das Benutzertoken in Authorization und das Gerätetoken als X-Device-Authorization: Bearer <device-token>. Der zusätzliche Nachweis wird auf Signatur, Aussteller, Workspace und Gerätestatus geprüft. Ein fehlender Nachweis führt zu 403 devices/device-token-required mit data.reason: device_proof_missing. Ein ungültiger, fehlerhaft formatierter oder nicht mehr verwendbarer Nachweis führt zu 403 devices/device-token-invalid mit device_proof_invalid. Für einen anderen Workspace gilt tenant_scope, für einen gültig authentifizierten Akteur ohne passende Geräteidentität wrong_actor_type. Das Erneuern des Benutzertokens behebt solche Gerätefehler nicht.

OperationBedeutung
POST /api/v2/devices/current/user-associationRegistriert eine neue menschliche Anmeldung mit Benutzer- und Gerätetoken, ohne Request-Body. Liefert 201, die Anmelde-ID und Location.
GET /api/v2/devices/current/user-associationLiest die Anmeldung genau dieser Benutzersession auf dem nachgewiesenen Gerät. Eine fremde Person oder unabhängige Session wird mit 404 verborgen.
POST /api/v2/devices/current/user-association/endBeendet nur expected_user_association_id. Geräteanmeldung und Fahrzeugzuordnung bleiben erhalten.
GET /api/v2/devices/current/vehicle-associationLiest den aktuellen Gerätekontext. Akzeptiert Benutzer- plus Gerätetoken oder das Gerätetoken als primären Bearer für die Wiederherstellung.
POST /api/v2/devices/current/vehicle-association/endLöst mit Selbstbedienungsberechtigung nur expected_vehicle_association_id; die Benutzeranmeldung bleibt bestehen.
POST /api/v2/devices/current/logoutVerwendet das Gerätetoken als primären Bearer. Beide erwarteten IDs sind erforderlich; senden Sie ausdrücklich null, wenn die jeweilige Zuordnung fehlt.

Die drei Beenden-/Abmelden-Aktionen liefern 200 mit dem abschließenden CurrentDeviceContext aus derselben Transaktion. Dieser enthält device_id, gegebenenfalls user_association_id und vehicle_association, aber keine Benutzerprofile oder Fahrzeugdetails. Verwenden Sie diesen Rückgabewert: Nach der Benutzerabmeldung kann die widerrufene Session keinen weiteren GET ausführen. Für die Wiederherstellung nach einer unklaren Antwort bleibt die geräteauthentifizierte Kontextabfrage verfügbar. Löschen Sie lokale Gerätezugangsdaten erst nach bestätigter Geräteabmeldung.

Ein Befehl, der eine registrierte menschliche Anmeldung benötigt, liefert 409 devices/current-user-association-required, wenn Benutzer- und Gerätenachweis nicht zur registrierten Session gehören. Diese Prüfung erfolgt vor dem Vergleich der erwarteten ID. Eine neuere eigene Anmeldung führt zu 409 devices/user-association-changed; eine geänderte Fahrzeugzuordnung zu 409 devices/vehicle-association-changed. Übernehmen Sie bei Wiederholungen niemals automatisch neuere IDs. Behalten Sie die ursprünglich bestätigten IDs und holen Sie für einen neuen Kontext eine neue Entscheidung ein. Eine bereits beendete Anmeldung kann ohne weitere Wirkung beendet werden. Ein Benutzertoken als primärer Bearer auf /logout führt zu 403 devices/device-token-required mit wrong_actor_type.

Für eine Anmeldung wird die verifizierte OIDC-Session an das Gerät gebunden. Eine bereits anderweitig gebundene Session führt zu 409; melden Sie sich mit einer unabhängigen Session an. Beim Abmelden wird diese Session lokal widerrufen, einschließlich später erneuerter Token. Weitere Anfragen erhalten 401 authentication-required mit data.reason: token_invalid. Andere unabhängige Sessions bleiben nutzbar. Die Bereinigung genau dieser exklusiv gebundenen Session beim Identitätsanbieter wird zuverlässig zur Verarbeitung vorgemerkt. Die Geräteanmeldedaten bleiben bei einer Benutzerabmeldung erhalten; das Zurücksetzen der Registrierung entfernt sie dagegen.

PATCH /api/v2/vehicle-device-associations/{association_id} erlaubt zwei Berechtigungswege:

  • Verwaltung: vehicles:update und devices:update, ohne zusätzlichen Gerätenachweis.
  • Standortquelle des eigenen Geräts: vehicles:device-location:use-self, passende registrierte Benutzersession, Gerätenachweis und Berechtigung für eine lesbare aktive Tour mit diesem Fahrzeug. Nur is_location_source und optional lock_version sind erlaubt. Ein allgemeines vehicles:read- oder Verwaltungsrecht ist nicht erforderlich. Andere Geräte sowie Modus und feste Quellenpräferenz können auf diesem Weg nicht geändert werden.

Tour-Start und Ad-hoc-Start verwenden einen einzigen device_context auf oberster Ebene mit expected_vehicle_association_id, auch wenn vehicle_use ein Fahrzeug auswählt. Bei aktivem use-vehicle stehen vehicle_id, optional replace_vehicle_id oder add, und device_context nebeneinander auf oberster Ebene. Ein Geräteheader ohne Kontext führt zu 422; Kontext ohne gültigen Nachweis führt zu 403. Ohne Geräteheader und Kontext kann ein Disponent eine Tour starten, ohne ein Smartphone als Quelle auszuwählen. Die Teilnehmerbereinigung erfolgt in jedem Fall atomar im Backend; eine Oberfläche soll dafür keine Kette einzelner Trennbefehle ausführen.

Ob die mobile App überhaupt über ihr registriertes Gerät authentifiziert, ist eine Workspace-Einstellung vom Administrator verwaltete Geräte (admin_managed_devices über GET/PATCH /api/v2/devices/settings, vor dem Login auch als x_tourfold_admin_managed_devices in der öffentlichen Frontend-Konfiguration sichtbar). Ist sie deaktiviert, verwendet die App von jedem Gerät aus den normalen Benutzer-Login und registriert das Gerät im Hintergrund selbst.

Scopes und Autorisierung​

Fordern Sie bei der Authentifizierung die üblichen OIDC-Scopes an:

  • openid — für OIDC-Konformität erforderlich
  • profile — Zugriff auf grundlegende Profil-Claims
  • email — Zugriff auf den E-Mail-Claim

Der Zugriff auf einzelne Ressourcen wird über die Rollen und Grants des Workspace des Aufrufers geregelt, nicht über OAuth-Scopes. Das Token identifiziert, wer Sie sind und in welchem Workspace Sie agieren; was Sie lesen oder schreiben dürfen, entscheiden die Rollenzuweisungen dieser Identität. Ein Token, das gültig ist, aber den erforderlichen Grant nicht besitzt, erhält 403 Forbidden; der fehlende Grant steht in data.required_grants, sofern er statisch bekannt ist.

Grants für Objekte und Datensätze sowie Zugriff je Typ​

Zum Lesen von Datensätzen ist objects:records:read erforderlich; Erstellen, Aktualisieren und Löschen verwenden die passenden Grants objects:records:*. Das Leserecht ist unabhängig, sodass eine rein lesende Integration kein Schreibrecht benötigt.

Objektdefinitionen sind für den Tenant sichtbare Metadaten. GET /api/v2/definitions/objects liefert den stabilen Objektkatalog; eine ACL je Typ blendet die Objektdefinition nicht aus. Der Versuch, verweigerte Datensätze zu lesen, liefert 403 access-denied mit data.reason: not_member.

Token-Verwaltung​

Ein Access-Token erneuern​

Access-Token sind kurzlebig. Verwenden Sie das Refresh-Token, um ein neues zu erhalten:

curl -X POST https://auth.tourfold.com/realms/tourfold-tenants/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "refresh_token=YOUR_REFRESH_TOKEN"

Eine Session widerrufen​

curl -X POST https://auth.tourfold.com/realms/tourfold-tenants/protocol/openid-connect/logout \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "refresh_token=YOUR_REFRESH_TOKEN"

Sicherheits-Best-Practices​

  • Bewahren Sie Token, Client-Secrets und private Schlüssel sicher auf — in Umgebungsvariablen oder einem Secrets-Manager, niemals in der Versionsverwaltung. Das Client-Secret eines Servicekontos wird nur einmal angezeigt; erneuern Sie es, falls es offengelegt worden sein könnte.
  • Behandeln Sie den Ablauf — implementieren Sie eine Refresh-Token-Logik für langlaufende Anwendungen; Servicekonten fordern vor exp und nach jedem 401 ein neues Token an.
  • Nur HTTPS verwenden — senden Sie Token niemals über unverschlüsselte Verbindungen.
  • Fordern Sie nur die Scopes an, die Sie benötigen.
  • Verwenden Sie einen eigenen Client je Umgebung — getrennte Clients/Anmeldedaten für Entwicklung, Staging und Produktion.

Enterprise: dedizierter Realm​

Standardmäßig authentifizieren sich alle Workspaces gegen den gemeinsamen tourfold-tenants-Realm. Enterprise-Workspaces können mit einem eigenen dedizierten Keycloak-Realm bereitgestellt werden — etwa um einen eigenen Identity-Provider / SSO, eigene Passwort- und Session-Richtlinien oder eine isolierte User-Federation einzubringen. Wird ein dedizierter Realm verwendet, wird das Segment tourfold-tenants in den obigen Endpoints durch den Realm-Namen des Workspace ersetzt, tf-<Workspace-ID>. Der token_endpoint eines Servicekontos nennt immer den richtigen Realm. Kontaktieren Sie den Support, um einen dedizierten Realm einzurichten.

Fehlerantworten​

Fehler bei Authentifizierung und Autorisierung sind RFC-9457-Problemdokumente und werden — wie jeder andere API-Fehler — als application/problem+json ausgeliefert. Zwei Statuscodes sind hier relevant:

  • 401 Unauthorized — die Anfrage enthielt keine verwendbare Identität. Behoben wird das durch das Beziehen oder Erneuern von Anmeldedaten.
  • 403 Forbidden — die Anfrage ist authentifiziert, aber diese Identität darf die Aktion nicht ausführen. Die Abhilfe hängt von data.reason ab: Fehlende Grants lassen sich vergeben; Eigentümer-, Mitgliedschafts- und Selbstzielregeln erfordern eine Änderung der Beziehung zwischen Aufrufer und Ressource.

Beide enthalten ein maschinenlesbares data.reason, damit ein Client das weitere Vorgehen ohne Auswertung des menschenlesbaren detail-Texts entscheiden kann.

Das unten beschriebene Autorisierungs-Vokabular gilt für access-denied und spezifischere Autorisierungsablehnungen. Ein typspezifischer 403-Fehler kann einen eigenen Ursachenwert definieren; tenant-disabled ist das bestehende, unten erläuterte Beispiel.

hinweis

Behandeln Sie data als optional — greifen Sie niemals ohne Existenzprüfung auf data.reason zu. Bei 401 und bei Autorisierungsablehnungen mit 403 ist data.reason immer vorhanden, und data.required_grants nur dann, wenn die Ablehnung auf Grants beruht und die erforderlichen Grants statisch bekannt sind (eine als eigene Regel implementierte Prüfung kann keine benennen).

401 — nicht authentifiziert​

Wird zurückgegeben, wenn der Authorization-Header fehlt oder das Token abgelaufen, fehlerhaft oder von einem nicht vertrauenswürdigen Issuer ausgestellt ist:

{
"type": "https://problems.tourfold.com/authentication-required",
"title": "Authentication required",
"status": 401,
"detail": "Valid authentication credentials are required",
"data": {
"reason": "token_expired"
}
}

Der Problemtyp type bleibt für alle drei Ursachen authentication-required — die Ursache steht in data.reason, nicht in einer separaten Typ-URI:

data.reasonUrsacheWas der Client tun soll
token_missingEs wurden überhaupt keine Anmeldedaten übermittelt.Über einen der oben beschriebenen Flows authentifizieren. Eine unveränderte Wiederholung scheitert identisch.
token_expiredEin wohlgeformtes Token, dessen Gültigkeit abgelaufen ist.Access-Token erneuern und die Anfrage einmal wiederholen. Nur diese Ursache rechtfertigt einen automatischen Retry.
token_invalidFehlerhaftes Token, ungültige Signatur oder nicht vertrauenswürdiger Issuer.Keinen blinden Retry ausführen — dasselbe Token scheitert weiterhin. Token verwerfen und neu authentifizieren.

Jede 401-Antwort enthält zusätzlich einen WWW-Authenticate-Header:

  • Ein Token wurde übermittelt, aber abgelehnt → der Challenge enthält die Fehlerparameter nach RFC 6750, zum Beispiel WWW-Authenticate: Bearer error="invalid_token", error_description="...".
  • Es wurde kein Token gesendet → ein einfaches WWW-Authenticate: Bearer.

Ein weiterer Problemtyp führt zu 401: https://problems.tourfold.com/login-failed („Login failed“). Er deckt einen abgelehnten Login mit Anmeldedaten ab, nicht ein fehlendes oder unbrauchbares Bearer-Token.

Token-Erneuerung implementieren​

Das Ursachen-Vokabular lässt sich direkt auf eine Refresh-Logik abbilden:

  1. 401 mit data.reason = token_expired → Refresh-Token gegen ein neues Access-Token tauschen und die ursprüngliche Anfrage einmal wiederholen.
  2. 401 mit data.reason = token_missing → es sind keine Anmeldedaten in der API angekommen. Client korrigieren und authentifizieren.
  3. 401 mit data.reason = token_invalid → abbrechen. Das zwischengespeicherte Token verwerfen und neu authentifizieren; eine Wiederholung scheitert garantiert und verbraucht nur Rate-Limit-Budget.
  4. Der Refresh-Aufruf selbst scheitert → das Refresh-Token ist abgelaufen oder widerrufen; den vollständigen Authorization-Flow erneut durchlaufen.

403 — authentifiziert, aber nicht berechtigt​

Wird zurückgegeben, wenn der Aufrufer bekannt ist, die Aktion aber nicht ausführen darf:

{
"type": "https://problems.tourfold.com/access-denied",
"title": "Access denied",
"status": 403,
"detail": "You don't have permission to perform this action",
"data": {
"reason": "missing_grant",
"required_grants": ["users:update"]
}
}

Bei access-denied und spezifischeren Autorisierungsablehnungen ist data.reason einer der folgenden Werte:

data.reasonBedeutung
missing_grantDem Aufrufer fehlt einer der für die Operation erforderlichen Grants.
not_ownerDer Aufrufer ist nicht der Eigentümer der Zielressource.
not_authorDer Aufrufer hat die Zielressource nicht erstellt.
not_memberDem Aufrufer fehlt die Mitgliedschaft in der Ressourcengruppe oder in einer Rolle, die die angeforderte Rolle zuweisen darf.
plan_restrictedDer Plan bzw. die Feature-Flags des Workspace enthalten diese Funktion nicht.
tenant_scopeDie Ressource gehört zu einem anderen Workspace als dem des Aufrufers.
self_targetDie Operation verbietet dem Aufrufer, sich selbst als Ziel auszuwählen. Zusätzliche Grants umgehen diese Regel nicht.
resource_lockedEine von einem anderen Akteur gehaltene Sperre verhindert die Aktion dieses Aufrufers. Ein Zustand, der alle Aufrufer blockiert, wird als fachlicher 409- oder 422-Fehler gemeldet.

Ein deaktivierter Workspace wird als typspezifisches Problem https://problems.tourfold.com/tenant-disabled mit data.reason = TENANT_INACTIVE gemeldet. Prüfen Sie zuerst type, bevor Sie typspezifische data-Felder auswerten; behandeln Sie TENANT_INACTIVE nicht als zusätzlichen Wert der geschlossenen Liste für Autorisierungsablehnungen.

data.required_grants listet die Grants auf, die die Prüfung erfüllt hätten. Das Feld ist nur vorhanden, wenn die Ablehnung grant-basiert ist und die erforderlichen Grants statisch bekannt sind — Clients müssen es deshalb als optional behandeln. Grant-Werte sind durch Doppelpunkte getrennt, zum Beispiel users:read, users:update, tenant:ownership:update, objects:configuration:update, webhooks:create.

Eine 403-Antwort zu wiederholen hilft für sich genommen nie: entweder benötigt der Aufrufer eine Rolle mit dem fehlenden Grant, oder die Aktion ist für diese Ressource nicht verfügbar.

Die interne Admin-Control-Plane (admin-v1) ist bewusst schlanker gehalten. Sie authentifiziert Aufrufer und liefert 401 in genau der oben beschriebenen Form, besitzt aber kein Autorisierungsmodell auf Grant-Ebene und erzeugt daher keine grant-basierten 403-Antworten.

Die meisten Workspace-bezogenen Operationen durchlaufen zusätzlich Prüfungen des Tenant-Zustands. Ein deaktivierter Workspace liefert 403 tenant-disabled; ein aufgrund der Abrechnung gesperrter Workspace liefert 402 tenant-billing-locked. Billing-Portal-, Zahlungsmethoden- und Billing-Recheck-Operationen bleiben erreichbar, damit der Workspace die Sperre beheben kann. Dabei handelt es sich um Fehler des Workspace-Zustands, nicht um Fehler der Token-Authentifizierung.

Ein in einem Workspace deaktivierter Benutzer behält eine gültige Anmeldung, weil eine Anmeldung zu mehreren Workspaces gehören kann. Sein Token wird daher nicht als 401 abgelehnt: jede Anfrage an diesen Workspace beantwortet das typspezifische Problem https://problems.tourfold.com/user-deactivated, mit dem Workspace in data.tenant_id:

{
"type": "https://problems.tourfold.com/user-deactivated",
"title": "User deactivated",
"status": 403,
"detail": "This user account is deactivated in this workspace",
"data": {
"tenant_id": "5f0c6a8e-3c1b-4d2a-9e7f-1a2b3c4d5e6f"
}
}

Erneuern Sie bei dieser Antwort weder das Token noch melden Sie sich erneut an; beides liefert ein Token, das genauso abgelehnt wird. Ein Workspace-Administrator muss den Benutzer wieder aktivieren. Ein dem Workspace unbekannter oder daraus gelöschter Benutzer erhält weiterhin 401 authentication-required.

Auf type und Status verzweigen, nicht auf detail​

Ein Feature kann anstelle des generischen access-denied einen spezifischeren, namensraumbezogenen Problemtyp zurückgeben — zum Beispiel https://problems.tourfold.com/comments/cannot-edit-others. Der status bleibt 403 und data.reason enthält weiterhin die grobe maschinenlesbare Ursache; Code, der auf Status plus data.reason prüft, funktioniert also weiter, während ein Client, der den genauen Fall benötigt, auf die spezifischere type-URI matchen kann.

type-URIs und HTTP-Statuscodes sind stabiler Vertragsbestandteil. title und detail sind menschenlesbar und können jederzeit umformuliert oder lokalisiert werden — verzweigen Sie niemals darauf.

Das vollständige problem+json-Format finden Sie unter Fehler, den kompletten Typkatalog in der Fehlertypen-Referenz.

Rate-Limiting​

Die Authentifizierung unterliegt dem Rate-Limiting. Einzelheiten finden Sie unter Rate-Limiting.

Nächste Schritte​