Der erste Aufruf mit curl

Nach dieser Anleitung haben Sie mit Ihrem Schlüssel zwei Routen aufgerufen — Ihr eigenes Konto und Ihre Playlisten — und die Kopfzeilen einer Antwort gesehen. Fünf Minuten, keine Installation außer curl.

Schritte#

1. Legen Sie Adresse und Schlüssel in Umgebungsvariablen ab. Der Schlüssel gehört in eine Kopfzeile, nie in die Adresse — Adressen landen in Protokollen, Kopfzeilen nicht.

   export SZENERA_API="https://<basis-adresse-ihrer-umgebung>"
   export SZENERA_API_KEY="ak_…"
   

2. Rufen Sie Ihr eigenes Konto ab. GET /v1/me liest das Benutzerprofil, dem der Schlüssel gehört — die Antwort hier auf die Felder gekürzt, die zählen:

   curl -sS "$SZENERA_API/v1/me" \
     -H "Authorization: Bearer $SZENERA_API_KEY"
   

   {
     "id": "usr_01KERQ74K0TEAM000000000001",
     "email": "owner@demo.local",
     "tenantId": "tnt_01KERPXZM0DEM0000000000001",
     "status": "active",
     "profile": { "displayName": "Julia Petersen", "locale": "de-DE", "timezone": "Europe/Berlin" },
     "roleAssignments": [
       { "roleId": "rol_01KERPYWXGRECHT00000000001", "assignedAt": "2026-01-12T09:05:00.000Z", "assignedById": "usr_01KERQ74K0TEAM000000000001", "expiresAt": null }
     ]
   }
   

   tenantId ist die Kennung Ihrer Organisation. Steht dort eine andere als erwartet, zeigt der Schlüssel woandershin, als gedacht.

3. Rufen Sie die Liste Ihrer Playlisten ab. GET /v1/playlists braucht das Recht playlist.list, das die Klassen Nur Lesen, Ausspielsteuerung und Vollzugriff enthalten — ein Schlüssel der Klasse Medien-Automation oder Inhalte-Pflege bekommt hier eine 403. Auch diese Antwort ist auf die wichtigsten Felder gekürzt:

   curl -sS "$SZENERA_API/v1/playlists?limit=5" \
     -H "Authorization: Bearer $SZENERA_API_KEY"
   

   {
     "items": [
       {
         "id": "pll_01KWV91ZS0PRGRAMM000000001",
         "name": "Tagesprogramm",
         "version": 6,
         "createdAt": "2026-07-06T08:35:00.000Z",
         "updatedAt": "2026-07-13T07:52:00.000Z",
         "items": [
           { "id": "pli_01KWV92A70PKT0000000000001", "kind": "scene", "sceneId": "scn_01KJPX8NH0SZENE00000000001", "sceneVersionId": null, "durationMs": 10000, "transition": null, "order": 0 }
         ]
       }
     ],
     "nextCursor": "cGxsOjIwMjYtMDMtMTE",
     "total": 2
   }
   

   Diese Liste nimmt limit zwischen 1 und 200 (Vorgabe 50) und blättert mit cursor weiter; nextCursor fehlt auf der letzten Seite. Die Displays (GET /v1/players) erreichen Sie mit einem Schlüssel genauso — fleet.player.list ist schlüsselfähig. Die Geräte dahinter (GET /v1/devices) nicht: identity.device.list ist nur für Benutzerkonten vorgesehen. Ein Display ist die Fläche, die etwas zeigt; ein Gerät die Maschine mit Zertifikat und Kopplung — und die bleibt Menschen vorbehalten.

4. Sehen Sie sich die Kopfzeilen an. Mit -i zeigt curl den Status und die Kopfzeilen vor dem Rumpf:

   curl -sSi "$SZENERA_API/v1/me" \
     -H "Authorization: Bearer $SZENERA_API_KEY" | head -n 12
   

   Zwei Zeilen zählen: Content-Type: application/json und X-Trace-Id: trc_…. Die Trace-Kennung ist die Spur dieses einen Aufrufs; notieren Sie sie, wenn etwas nicht stimmt.

Derselbe Aufruf mit der Kommandozeile#

Die Kommandozeile szenera nimmt Adresse und Schlüssel aus Umgebungsvariablen und spricht dieselben Routen; ist die Standardausgabe kein Terminal, gibt sie JSON aus. Den Schlüssel liest sie aus demselben SZENERA_API_KEY wie in Schritt 1, die Adresse aus SZENERA_BASE_URL:

SZENERA_BASE_URL="$SZENERA_API" szenera whoami
SZENERA_BASE_URL="$SZENERA_API" szenera playlist list --limit=5

Wie Sie an die Kommandozeile kommen, steht unter Die CLI beziehen.

Ergebnis prüfen#

• Beide Aufrufe antworten mit 200 und einem JSON-Rumpf; Fehler kämen als Rumpf mit code, message und traceId.
• Die Liste der Playlisten trägt items und, solange weitere Seiten folgen, nextCursor.
• Im Portal steht der Schlüssel unter Einstellungen › Organisation › API-Schlüssel jetzt mit einem Zeitpunkt in Zuletzt benutzt.

Wenn etwas nicht klappt#

Weiterführendes#

• Was eine Antwort enthält
• Wenn der erste Aufruf scheitert
• Paginierung