# Wie läuft ein Aufruf durch die Plattform?

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.

> **Typ:** konzept
> **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

## 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`.

![Ein Aufruf läuft vom Client über Ausweis-Erkennung, Route und Rechteprüfung zur Antwort; unbekannter Ausweis und fehlendes Recht zweigen in den Fehlerrumpf ab](/de/getting-started/bilder/ee0e976f-request-flow.svg)

_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 auf `message`.** Der Code ist stabil und Teil des Vertrags; der Text darf sich ändern.
- **Protokollieren Sie die Trace-Kennung.** `X-Trace-Id` und `traceId` sind 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 `403` auf, ein zu weiter an gar nichts.

## Weiterführendes

- [Einen API-Schlüssel erzeugen](/de/getting-started/create-api-key)
- [Anmeldung](/de/api/authentication)
- [Fehlerformat](/de/api/error-format)