Wie läuft ein Aufruf durch die Plattform?
Von der Bearer-Kopfzeile über die Rechteprüfung bis zur Antwort mit Trace-Kennung: die Stationen, die jeder Aufruf durchläuft.
3 Minuten LesezeitErste SchritteStand: 25.10.2026
Auf dieser Seite
Bevor Sie loslegen
- Für wen
- Entwicklerinnen und Entwickler vor dem ersten Aufruf gegen die Szenera-API
- Voraussetzung
- keine — die Seite erklärt, was ein API-Schlüssel später auslöst
Jeder Aufruf durchläuft dieselben drei Stationen: Die Plattform erkennt den Ausweis, wählt die Operation unter /v1 und prüft deren Recht, dann antwortet sie mit JSON und den Kopfzeilen, die überall gelten. Wer diese Stationen kennt, liest jede Fehlerantwort auf den ersten Blick.
Station 1: Der Ausweis in der Bearer-Kopfzeile
Die Plattform erkennt am Präfix des Werts in Authorization: Bearer …, welche Art Ausweis vorliegt — ohne weitere Angabe von Ihnen:
| Präfix | Ausweis | Für wen |
|---|---|---|
ak_ |
API-Schlüssel einer Organisation | Maschinen: Skripte, Dienste, Ihre Anbindung |
eyJ |
Sitzungstoken aus POST /v1/auth/login |
Menschen im Portal; 15 Minuten gültig, danach Auffrischung |
oat_ |
Zugriffstoken eines delegierten Zugangs | eine fremde Anwendung im Namen eines Menschen |
opk_ |
Schlüssel des Plattformbetriebs | nur der Betreiber der Plattform |
rdr_ |
Renderer-Token | der Abspielprozess eines gekoppelten Geräts |
Am Rand begegnen Ihnen sct_ (ein Verzeichnisdienst unter /scim/v2, sonst nirgends), inv_ (Einladung vor der ersten Anmeldung) und dev_ (Erst-Registrierung eines Geräts); Geräte im Betrieb weisen sich mit ihrem Zertifikat aus. Für Ihre Anbindung ist ak_… der Regelweg: kein Ablauf nach einer Viertelstunde, keine Auffrischung.
Ein Wert mit unbekanntem Präfix gilt ausdrücklich nicht als anonym: Er wird als unbrauchbarer Ausweis mit 401 Auth.Required abgewiesen — ein Tippfehler im Präfix wird so zu einer 401, nicht zu einer irreführenden 404. Dieselbe Antwort bekommt ein Aufruf ohne Kopfzeile; ein Schlüssel mit richtigem Präfix, aber abgeschnittenem Wert bekommt 401 Auth.TokenMalformed.
Station 2: Route und Rechteprüfung
Jede Route, über die Szenera selbst entscheidet, liegt unter /v1, und der Pfad ist Teil des Vertrags; nur wo ein fremder Standard seine Adresse vorschreibt, fehlt das Präfix (/oauth/…, /.well-known/…, /scim/v2/…). Dann prüft die Plattform je Operation das Recht, das die Referenz bei ihr nennt (zum Beispiel playlist.list für GET /v1/playlists). Ein API-Schlüssel trägt die feste Liste von Rechten aus dem Anlegen; Geräte, das Koppeln und Löschen von Displays und die Schlüsselverwaltung bleiben Benutzerkonten vorbehalten. Fehlt das Recht: 403 Permission.Denied. Routen des Plattformbetriebs antworten einem Schlüssel einer Organisation mit 403 Permission.OperatorOnly.
Der Fehlerzweig trägt denselben Rumpf wie jeder Fehler: code, message, traceId.
Station 3: Die Antwort und ihre Kopfzeilen
Die Plattform spricht JSON. Vier Kopfzeilen prägen den Austausch — drei in der Antwort, eine in der Anfrage — überall dort, wo ihre Bedingung erfüllt ist:
| Kopfzeile | Wann |
|---|---|
X-Trace-Id |
immer — die Spur-Kennung dieses Aufrufs |
If-Match (Anfrage) |
bei Änderungen versionierter Ressourcen (Szenen, Playlisten, Programme, Rollen, Displays): die gelesene version geht als If-Match mit, dieselbe Zahl steht als ETag in der Antwort |
Idempotent-Replay: true |
wenn eine Wiederholung mit demselben Idempotency-Key die gespeicherte Antwort erhielt |
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset |
nur auf gedrosselten Routen — vor allem Anmeldung, Registrierung, Passwort-Zurücksetzen |
Ein Fehler kommt immer im selben Rumpf: code in der Form Bereich.Ursache, message als Kurztext und traceId mit dem Präfix trc_. Der HTTP-Status folgt dem Bereich des Codes: Auth.* → 401, Permission.* → 403, *.NotFound → 404, Conflict.* → 409, Validation.* → 422, RateLimit.* → 429.
Was daraus folgt
- Schlüssel statt Sitzung für Maschinen. Ein Sitzungstoken läuft nach 15 Minuten ab; ein Schlüssel
ak_…nicht. - Schalten Sie auf
code, nie aufmessage. Der Code ist stabil und Teil des Vertrags; der Text darf sich ändern. - Protokollieren Sie die Trace-Kennung.
X-Trace-IdundtraceIdsind derselbe Wert — das, was Sie bei einer Rückfrage nennen. - Geben Sie dem Schlüssel nur die Rechte, die Ihre Anbindung braucht. Ein zu enger Schlüssel fällt an einer
403auf, ein zu weiter an gar nichts.