Anmeldung: Schlüssel und Sitzungen

Jeder Aufruf weist sich mit der Kopfzeile Authorization: Bearer <wert> aus; die API erkennt die Art des Ausweises am Präfix des Werts. Für Integrationen ist der API-Schlüssel der Regelweg. Diese Seite nennt die Präfixe, die Regeln für Schlüssel, ihren Lebenszyklus und wann eine Sitzung die bessere Wahl ist.

Die Präfixe#

ak_ und opk_ sind eigenständige Präfixe: opk_ beginnt nicht mit ak_. Ein Schlüssel sagt damit selbst, welcher Sorte er angehört. Nicht zu verwechseln sind die Geheimwerte mit den Kennungen ihrer Datensätze (akm_, sctm_, oac_): Die stehen in Listen und Protokollen, der Geheimwert selbst nur ein einziges Mal in der Antwort auf seine Ausstellung.

Ein sct_ kommt auf keine andere Route als /scim/v2 — überall sonst wird er mit 403 abgewiesen. Umgekehrt erreicht kein ak_ und kein oat_ die SCIM-Fläche.

Ein Wert mit unbekanntem Präfix gilt als unbekannt, nicht als anonym: Die Antwort ist 401, nicht 404. Ohne Kopfzeile erreichen Sie nur öffentliche Routen — etwa GET /v1/openapi.json, GET /health/ready oder POST /v1/auth/login. In der Referenz erkennen Sie sie an einer leeren security-Liste und dem Satz „Öffentlich — keine Anmeldung erforderlich“. Genau 46 der 443 Operationen sind so.

Der API-Schlüssel#

Welche Rechte ein Schlüssel tragen kann, sagt GET /v1/permission-catalog — ohne besonderes Recht, nur mit Anmeldung. Jeder Eintrag trägt appliesTo; nur Rechte mit apiKey in dieser Liste sind schlüsselfähig. Im Kern-Katalog sind das heute 56 Rechte: Medien (asset.*), Szenen und Layout-Vorlagen (scene.*, layout-template.*), Playlisten und Programme (playlist.*, schedule.*), Standorte (location.*), die Displays (fleet.player.list, fleet.player.read, fleet.player.update, fleet.player.command.issue), die Web-Displays (fleet.web-display.manage), die Werbung (alle acht advertising.*), die Nachweise (analytics.proof.read, analytics.proof.manage) sowie billing.usage.read und analytics.query.run. Nicht schlüsselfähig sind unter anderem die Geräteliste identity.device.list, die Wiedergabe-Rückschau fleet.playback-history.read, das Anlegen und Entfernen von Displays (fleet.player.pair, fleet.player.delete), die Kontoverwaltung identity.*, die Webhook-Verwaltung webhook.* und alles unter platform.*. Was dort steht, bleibt Sitzungen vorbehalten.

Die Kommandozeile zeigt die Freigabeliste: szenera api-key issue --list-allowed; den ganzen Katalog: szenera permission catalog.

Ein Schlüssel handelt mit den Rechten des Kontos, das ihn erstellt hat. Ist dieses Konto gesperrt, ruht der Schlüssel: Die Anmeldung antwortet 401 Auth.UserSuspended, und nach dem Aufheben der Sperre arbeitet er wieder. Wird das Konto gelöscht, ist der Schlüssel widerrufen (Grund user-deleted-cascade). Dasselbe gilt für eine verbundene Anwendung und das Konto, das ihr zugestimmt hat.

Unter /v1/me erreicht ein Schlüssel nur die Lesewege, die ein Programm braucht: GET /v1/me (wer der Ausweis ist), GET /v1/me/permissions, GET /v1/me/capabilities, GET /v1/me/apps/store und GET /v1/me/licensing. Alles Übrige dort gehört der Person und verlangt eine Sitzung.

lastUsedAt zeigt die letzte Nutzung. Der Wert wird höchstens einmal je Minute fortgeschrieben.

Lebenszyklus eines Schlüssels#

curl -sS -X POST "$SZENERA_API/v1/me/api-keys/akm_01KQRWJRC0APKEY00000000001/rotate" \
  -H "Authorization: Bearer $SZENERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "graceHours": 24 }'

Die Antwort — beide Schlüsselobjekte hier auf die Felder gekürzt, die eine Integration braucht:

{
  "newApiKey": {
    "id": "akm_01KQRWJRC0APKEY00000000002",
    "keyPrefix": "ak_APKEY0002",
    "name": "Warenwirtschaft-Anbindung",
    "originClass": "read-only",
    "scope": ["asset.read", "playlist.read"],
    "expiresAt": "2027-05-04T07:00:00.000Z",
    "revokesAt": null
  },
  "newPlainKey": "ak_01KQRWJRC0APKEY00000000002",
  "oldApiKey": {
    "id": "akm_01KQRWJRC0APKEY00000000001",
    "keyPrefix": "ak_APKEY0001",
    "name": "Warenwirtschaft-Anbindung",
    "originClass": "read-only",
    "scope": ["asset.read", "playlist.read"],
    "expiresAt": "2027-05-04T07:00:00.000Z",
    "revokesAt": "2026-07-21T09:15:00.000Z"
  },
  "oldRevokesAt": "2026-07-21T09:15:00.000Z"
}

Im Portal finden Sie dieselben Vorgänge unter Einstellungen › Organisation › API-Schlüssel mit den Schaltflächen Schlüssel erstellen, Rotieren und Widerrufen; die Gnadenfrist heißt dort Alter Schlüssel gültig bis mit den Stufen Sofort ungültig, 1 Stunde, 24 Stunden und 3 Tage. Wie Sie den ersten Schlüssel anlegen, steht unter Einen API-Schlüssel erzeugen.

Die Antworten auf einen ungültigen Schlüssel: 401 Auth.ApiKeyUnknown, 401 Auth.ApiKeyExpired, 401 Auth.ApiKeyRevoked — alle unter Fehlercodes: auf jeder Route möglich.

Die Sitzung#

Eine Sitzung ist der Weg für Oberflächen und für Menschen an der Kommandozeile — dort heißt sie Ausweisart password. Sie braucht Auffrischung, ein Schlüssel nicht.

Fachliche Anfragen werden nicht über Cookies authentisiert — der Bearer-Kopf ist immer der Ausweis. Gehört ein Konto zu mehreren Organisationen, endet die Anmeldung in organization-choice; ein Schlüssel kennt diese Frage nicht, er gehört genau einer Organisation.

Die Unternehmens-Anmeldung über den Anbieter Ihrer Organisation und die plattformweiten Anbieter sind Rundläufe durch den Browser, keine Integrationswege; wie Sie sie einrichten, steht im Handbuch unter Organisation.

Schlüssel oder Sitzung?#

Weiterführendes#

• Einen API-Schlüssel erzeugen
• Delegierter Zugang mit OAuth 2.1
• Provisionierung mit SCIM 2.0
• Fehlercodes: Konten und Sitzungen
• Handbuch: Organisation