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)
- 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
- 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:
| Feld | Verwendung |
|---|---|
client_id | die Client-ID (tf-sa-<Servicekonto-ID>) |
client_secret | das 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_endpoint | wo 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.
| Operation | Bedeutung |
|---|---|
POST /api/v2/devices/current/user-association | Registriert 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-association | Liest 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/end | Beendet nur expected_user_association_id. Geräteanmeldung und Fahrzeugzuordnung bleiben erhalten. |
GET /api/v2/devices/current/vehicle-association | Liest 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/end | Löst mit Selbstbedienungsberechtigung nur expected_vehicle_association_id; die Benutzeranmeldung bleibt bestehen. |
POST /api/v2/devices/current/logout | Verwendet 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:updateunddevices: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. Nuris_location_sourceund optionallock_versionsind erlaubt. Ein allgemeinesvehicles: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 erforderlichprofile— Zugriff auf grundlegende Profil-Claimsemail— 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
expund nach jedem401ein 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 vondata.reasonab: 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.
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.reason | Ursache | Was der Client tun soll |
|---|---|---|
token_missing | Es wurden überhaupt keine Anmeldedaten übermittelt. | Über einen der oben beschriebenen Flows authentifizieren. Eine unveränderte Wiederholung scheitert identisch. |
token_expired | Ein wohlgeformtes Token, dessen Gültigkeit abgelaufen ist. | Access-Token erneuern und die Anfrage einmal wiederholen. Nur diese Ursache rechtfertigt einen automatischen Retry. |
token_invalid | Fehlerhaftes 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:
401mitdata.reason=token_expired→ Refresh-Token gegen ein neues Access-Token tauschen und die ursprüngliche Anfrage einmal wiederholen.401mitdata.reason=token_missing→ es sind keine Anmeldedaten in der API angekommen. Client korrigieren und authentifizieren.401mitdata.reason=token_invalid→ abbrechen. Das zwischengespeicherte Token verwerfen und neu authentifizieren; eine Wiederholung scheitert garantiert und verbraucht nur Rate-Limit-Budget.- 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.reason | Bedeutung |
|---|---|
missing_grant | Dem Aufrufer fehlt einer der für die Operation erforderlichen Grants. |
not_owner | Der Aufrufer ist nicht der Eigentümer der Zielressource. |
not_author | Der Aufrufer hat die Zielressource nicht erstellt. |
not_member | Dem Aufrufer fehlt die Mitgliedschaft in der Ressourcengruppe oder in einer Rolle, die die angeforderte Rolle zuweisen darf. |
plan_restricted | Der Plan bzw. die Feature-Flags des Workspace enthalten diese Funktion nicht. |
tenant_scope | Die Ressource gehört zu einem anderen Workspace als dem des Aufrufers. |
self_target | Die Operation verbietet dem Aufrufer, sich selbst als Ziel auszuwählen. Zusätzliche Grants umgehen diese Regel nicht. |
resource_locked | Eine 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
- Lernen Sie die API-Grundlagen kennen
- Verstehen Sie das Erstellen & Aktualisieren von Ressourcen
- Erkunden Sie Paginierung, Sortierung & Filterung