# Einen API-Schlüssel erzeugen

Nach dieser Anleitung besitzen Sie einen Schlüssel `ak_…` mit genau den Rechten, die Ihre Anbindung braucht, und einem Ablaufdatum. Der Klartext erscheint genau einmal — beim Erstellen.

> **Typ:** anleitung
> **Für wen:** Entwicklerinnen und Entwickler, die eine Anbindung an die Szenera-API aufbauen
> **Voraussetzung:** ein Konto mit dem Recht `identity.api-key.create` (in der Vorgabe: Rolle Inhaber) in einer Organisation, deren Paket den API-Zugang enthält — ab dem Paket Premium („API und Webhooks“) und bei Enterprise, oder vertraglich freigeschaltet
> **Ort im Portal:** **Einstellungen › Organisation › API-Schlüssel**

## Schritte

1. Öffnen Sie **Einstellungen › Organisation › API-Schlüssel** und klicken Sie auf **Schlüssel erstellen**. Der Dialog **API-Schlüssel erstellen** öffnet sich: „Legen Sie Name und Rechte fest. Der Klartext-Schlüssel erscheint danach genau einmal.“
2. Tragen Sie unter **Name** (1) ein, wofür der Schlüssel da ist — das Portal schlägt „CI-Import“ als Beispiel vor. Der Name steht später in der Liste und in Protokollen.
3. Wählen Sie unter **Rechte** (2) eine **Klasse** — vorgewählt ist **Nur Lesen**:

   | Klasse | Was der Schlüssel darf |
   |---|---|
   | **Nur Lesen** | Inhalte, Medien, Zeitpläne, Standorte, Displays, Werbung und Nachweise abrufen — nichts verändern. |
   | **Medien-Automation** | Medien hochladen und Ordner verwalten. |
   | **Inhalte-Pflege** | Szenen und Vorlagen anlegen und ändern. |
   | **Ausspielsteuerung** | Playlisten und Zeitpläne verwalten. |
   | **Vollzugriff** | Alles, was Ihr Konto über die API darf. |
   | **Individuell** | Rechte einzeln, mit Erklärung je Recht. |

   Unter den Karten steht, wie viele Rechte die Wahl enthält — bei **Nur Lesen** mit den vollen Rechten der Rolle Inhaber „Enthält 19 Rechte.“; die Zahl ist auf Ihre eigenen Rechte beschnitten. Mit **Einzelne Rechte anpassen** (3) öffnen Sie die Auswahl aus dem Rechte-Katalog (**Recht suchen …**, **Recht hinzufügen**); bei **Individuell** ist sie sofort offen.
4. Wählen Sie unter **Gültig bis** (4) die Laufzeit: **In 30 Tagen**, **In 90 Tagen** (Vorgabe), **In einem Jahr** oder **Unbefristet**. Unbefristete Schlüssel markiert die Liste eigens.
5. Wählen Sie unter **Alter Schlüssel gültig bis** (5), wie lange bei einer späteren Rotation der alte Wert neben dem neuen gilt: **Sofort ungültig**, **1 Stunde**, **24 Stunden** (Vorgabe) oder **3 Tage**.
6. Klicken Sie auf **Erstellen** (6). Der Kasten **API-Schlüssel — nur jetzt sichtbar** zeigt den Klartext: „Jetzt kopieren und sicher ablegen; er wird nie wieder angezeigt.“ Klicken Sie auf **Schlüssel kopieren**, legen Sie den Wert in Ihrem Geheimnis-Speicher ab und bestätigen Sie mit **Verstanden**.

![Der Dialog „API-Schlüssel erstellen“ mit dem Feld Name (1), den Klassenkarten unter Rechte (2), der Schaltfläche Einzelne Rechte anpassen (3), den Auswahlfeldern Gültig bis (4) und Alter Schlüssel gültig bis (5) sowie der Schaltfläche Erstellen (6)](/de/getting-started/bilder/d5d2d429-create-api-key-dialog.png)

_Die Ziffern im Bild bezeichnen die Bedienelemente, nicht die Schritte. Klasse, Laufzeit und Rotationsfrist stehen zusammen in einem Dialog — der Klartext erscheint erst danach._

Drei Regeln gelten bei jeder Wahl: Ein Schlüssel kann nie mehr, als Sie selbst dürfen — die Klassen sind auf Ihre eigenen Rechte beschnitten. Nur schlüsselfähige Rechte stehen zur Wahl. Eine Klasse wird beim Anlegen in konkrete Rechte aufgelöst und danach nicht nachgeführt: Wächst der Rechte-Katalog, darf ein bestehender Schlüssel nicht über Nacht mehr.

## Optionen

**Rotieren.** Über **Aktionen › Rotieren** öffnet sich **Schlüssel rotieren**: Der Schlüssel „bekommt einen Nachfolger mit denselben Rechten. Der neue Schlüssel wird Ihnen einmalig angezeigt.“ Sie wählen, wie lange der alte daneben gilt (**Sofort ungültig** bis **3 Tage**); die Meldung „Schlüssel rotiert — der alte gilt noch bis …“ nennt den Zeitpunkt.

**Widerrufen.** Über **Aktionen › Widerrufen** und die Rückfrage **Schlüssel widerrufen?** wird der Schlüssel sofort und endgültig ungültig; laufende Integrationen verlieren den Zugang.

**Über die API.** `POST /v1/me/api-keys` legt denselben Schlüssel an (Recht `identity.api-key.create`). Ein Schlüssel kann keinen weiteren ausstellen; die Route erwartet ein Sitzungstoken (`eyJ…`) aus `POST /v1/auth/login`. Rumpf: `name`, `scope` (Liste der Rechte, mindestens eines), `expiresAt` (Pflicht; `null` heißt unbefristet), optional `originClass` (nur die Herkunft zur Anzeige — die Rechte selbst müssen in `scope` stehen; Vorgabe `custom`) und `rotationGraceHours` (0–72, Vorgabe 24); die Antwort `201` trägt den Klartext einmalig unter `plainKey`. Felder und Lebenszyklus: [Anmeldung: Schlüssel und Sitzungen](/de/api/authentication).

**Über die Kommandozeile.** `szenera api-key issue --name="Mediathek-Roboter" --permissions=asset.list,asset.read`; `--list-allowed` zeigt die freigegebenen Rechte. Der Befehl braucht ein Profil mit Kennwort-Anmeldung, kein Schlüssel-Profil (siehe [Profile und Ausweis](/de/cli/profiles-and-credentials)); alle Flaggen: [Befehle für Ihre Organisation](/de/cli/commands-organization).

## Ergebnis prüfen

- Der Aufruf `GET /v1/me` mit der Kopfzeile `Authorization: Bearer ak_…` antwortet mit `200` und Ihrem Konto (siehe [Der erste Aufruf mit curl](/de/getting-started/first-call)).
- Die Liste unter **Einstellungen › Organisation › API-Schlüssel** zeigt den neuen Eintrag mit **Name / Rechte**, **Klasse**, **Erstellt von**, **Gültig bis** und **Zuletzt benutzt** — zuerst „Nie benutzt“, nach dem ersten Aufruf mit Zeitpunkt.
- `GET /v1/me/api-keys` liefert Ihre eigenen Schlüssel — auch mit dem neuen Schlüssel selbst aufgerufen: die Kennung `akm_…` und den Präfix `ak_` plus neun Zeichen, nie den Klartext. Alle Schlüssel der Organisation zeigt `GET /v1/api-keys` (Recht `identity.api-key.list`).

## Wenn etwas nicht klappt

| Symptom | Bedeutung | Lösung |
|---|---|---|
| **Schlüssel erstellen** ist gesperrt; darüber steht „Bestehende Schlüssel arbeiten weiter und lassen sich jederzeit widerrufen. Neue auszustellen oder zu erneuern, geht ab dem Paket …“ | Das Paket der Organisation enthält den API-Zugang nicht. | Paket ab Premium wählen oder die Freischaltung vertraglich vereinbaren; bestehende Schlüssel arbeiten weiter. |
| Die API antwortet auf `POST /v1/me/api-keys` mit `402 Billing.AddonRequired` | Dasselbe über die API: Die Fähigkeit API-Zugang fehlt. | wie oben |
| Eine Klasse enthält weniger Rechte als erwartet | Die Klasse ist auf Ihre eigenen Rechte beschnitten. | Ein Konto mit den fehlenden Rechten legt den Schlüssel an, oder Ihre Rolle wird erweitert. |
| `403 Permission.Denied` auf `POST /v1/me/api-keys` mit einem Schlüssel `ak_…` | Ein Schlüssel kann keinen Schlüssel ausstellen. | Sitzungstoken verwenden oder den Weg über das Portal nehmen. |
| `403 ApiKey.ScopeEscalationBlocked` | Der angeforderte Umfang übersteigt Ihre eigenen Rechte. | Umfang verkleinern. |
| `422 ApiKey.ScopeNotKeyCapable` | Ein gewähltes Recht ist für Schlüssel nicht vorgesehen; `details` nennt es. | Recht entfernen; `szenera api-key issue --list-allowed` zeigt die zulässigen. |
| Sie sehen nur Ihre eigenen Schlüssel („Sie sehen hier Ihre eigenen Schlüssel. Die Schlüssel anderer Mitglieder sind Konten mit Verwaltungsrecht vorbehalten.“) | Ihnen fehlt `identity.api-key.list`. | Ein Konto mit diesem Recht sieht alle Schlüssel der Organisation. |

## Weiterführendes

- [Der erste Aufruf mit curl](/de/getting-started/first-call)
- [Anmeldung](/de/api/authentication)
- [Bereich Entwickler im Handbuch](https://szenera.com/de/docs/developers)