Authentifizierung

Die API nutzt OAuth2 client_credentials — den Grant für Maschine-zu-Maschine. Es gibt keinen Benutzer, keine Browser-Weiterleitung und keinen Zustimmungsbildschirm.

Zwei Hosts sind beteiligt, und dein Client spricht mit beiden:

Rolle	Host	Zweck
Identitätsanbieter	https://auth.shiftavo.com	stellt Token aus
Shard	aus dem Claim api_base deines Tokens	liefert die Daten

Deine Zugangsdaten übermitteln

Beide Standardverfahren zur Client-Authentifizierung aus OAuth2 (RFC 6749 §2.3.1) werden akzeptiert. Nimm das, was deine HTTP- oder OAuth-Bibliothek dir leicht macht — hier sind sie gleichwertig.

client_secret_post — Zugangsdaten im Formular-Body:

POST /identity/o/api/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=cust-acme-integration
client_secret=<secret>
scope=shifts.read

client_secret_basic — Zugangsdaten in einem HTTP-Basic-Header, nur client_id im Body:

POST /identity/o/api/token HTTP/1.1
Authorization: Basic base64("cust-acme-integration:<secret>")
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=cust-acme-integration
scope=shifts.read

client_secret_basic ist der Standard der Spezifikation und das, was die meisten fertigen OAuth-Bibliotheken senden; client_secret_post lässt sich von Hand einfacher bauen, ganz ohne Base64-Schritt.

Ablauf und Erneuerung

Token laufen standardmässig nach 1800 Sekunden ab. Der Grant client_credentials hat kein Refresh-Token — so vorgesehen (RFC 6749 §4.4.3), und es kostet dich nichts: Dein Client hält client_id und client_secret ohnehin, das «Erneuern» ist also nur ein neuer Token-Aufruf mit denselben Daten. Ein Refresh-Token wäre bloss ein weiteres Geheimnis zum Aufbewahren.

Zwei Regeln machen einen Client robust:

• Speichere das Token zwischen und verwende es bis kurz vor expires_in. Wer rund 30 Sekunden früher erneuert, vermeidet Rennen am Ablaufrand.

• Bei einem 401 von der Daten-API — ein Token kann vorzeitig ungültig werden, etwa durch eine Schlüsselrotation — verwirf das zwischengespeicherte Token, hol ein neues und wiederhol die Anfrage einmal.

Routing: der Claim api_base

Das Token ist ein JWT. Über die üblichen OAuth-Felder hinaus enthält es:

Claim	Beispiel	Bedeutung
api_base	https://app.shiftavo.com	Basis-URL des aufzurufenden Hosts
aud	["https://app.shiftavo.com/api"]	API des Ziel-Shards
tenant_id	0194d1c0-…	Das Unternehmen, an das du gebunden bist
tenant_name	Acme	Anzeigename
tenant_status	active	Nicht aktive Unternehmen erhalten kein Token

Lies api_base und ruf diesen Host auf. Halte einen konfigurierten Rückfallwert bereit, falls der Claim fehlt, aber bevorzug den Claim: Er ist es, der uns erlaubt, einen Shard hinzuzufügen oder zu verschieben, ohne dass sich bei dir etwas ändert.

aud und die Unternehmensbindung werden serverseitig aus dem Mandanten gesetzt, zu dem deine Zugangsdaten gehören. Sie sind nicht anforderbar — ein Client kann schlicht kein anderes Unternehmen und keinen anderen Shard ansprechen.

Was ein Maschinentoken nicht ist

Maschinentoken haben kein sub und keine Benutzer- oder Mitgliedschafts-Claims. Jeder Aufruf handelt als die Anbindung selbst, begrenzt durch ihre Scopes. Zwei Folgen:

• Die API kann nicht ableiten, wer für einen Schreibvorgang verantwortlich ist; deshalb verlangen manche Schreibvorgänge, dass du eine Person ausdrücklich nennst — siehe Den Menschen hinter einem Schreibvorgang benennen.

• Ein Benutzertoken aus unseren eigenen Apps (Web oder Mobile) wird auf dieser Schnittstelle abgelehnt. Sie ist ausschliesslich für Maschinen.

Fehler in dieser Phase

Symptom	Ursache
401 vom Token-Endpunkt	falsche client_id / client_secret, oder das Unternehmen ist gesperrt
400 invalid_scope am Token-Endpunkt	du hast einen Scope angefordert, der deinem Client nicht erteilt wurde
401 von der Daten-API	abgelaufenes, ungültiges oder vorzeitig entwertetes Token — erneuern und einmal wiederholen
403 insufficient_scope von der Daten-API	gültiges Token, fehlende Berechtigung — siehe Scopes