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.

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.

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.

Ü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); alle Flaggen: Befehle für Ihre Organisation.

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

Weiterführendes#

• Der erste Aufruf mit curl
• Anmeldung
• Bereich Entwickler im Handbuch