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

> **Typ:** anleitung
> **Für wen:** Entwicklerinnen und Entwickler mit einem frisch erzeugten API-Schlüssel
> **Voraussetzung:** ein Schlüssel `ak_…` mit dem Recht `playlist.list` (Klasse **Nur Lesen** genügt) und die Basis-Adresse Ihrer Umgebung — der Ursprung, den auch Ihr Portal anspricht
> **Ort:** Kommandozeile

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

   ```bash
   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:

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

   ```json
   {
     "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:

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

   ```json
   {
     "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:

   ```bash
   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`:

```bash
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](/de/cli/get-cli).

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

| Symptom | Bedeutung | Lösung |
|---|---|---|
| `401` mit `Auth.Required` | Kopfzeile fehlt, `Bearer` fehlt, oder der Wert hat kein bekanntes Präfix (Tippfehler im Präfix). | Kopfzeile und Variable prüfen; siehe [Wenn der erste Aufruf scheitert](/de/getting-started/troubleshooting). |
| `401` mit `Auth.TokenMalformed` | Das Präfix `ak_` stimmt, aber der Schlüssel ist abgeschnitten oder enthält ungültige Zeichen. | Den Wert vollständig aus dem Geheimnis-Speicher übernehmen: `ak_` plus 26 Zeichen. |
| `401` mit `Auth.ApiKeyUnknown`, `Auth.ApiKeyRevoked` oder `Auth.ApiKeyExpired` | Der Schlüssel existiert nicht, wurde widerrufen oder ist abgelaufen. | Neuen Schlüssel erzeugen. |
| `403` mit `Permission.Denied` | Der Schlüssel trägt das Recht der Operation nicht — oder die Route verlangt ein Recht, das Schlüssel nie tragen (Geräte, Koppeln und Löschen von Displays, Schlüsselverwaltung). | Klasse oder Rechte beim Erzeugen anpassen; für diese Routen ein Sitzungstoken verwenden. |
| `404` mit `Resource.NotFound` | Der Pfad trifft keine Route — meist fehlt `/v1`, oder die Basis-Adresse ist falsch. | Adresse und Pfad prüfen. |
| `422` mit `Validation.Failed` | Ein Parameter ist ungültig, etwa `limit=500`. | `details.issues` lesen und den Wert korrigieren. |

## Weiterführendes

- [Was eine Antwort enthält](/de/getting-started/response-contents)
- [Wenn der erste Aufruf scheitert](/de/getting-started/troubleshooting)
- [Paginierung](/de/api/pagination)