# API-Schlüssel (https://docs.pixl.lennox.zip/sdk/api-keys)

> Schlüssel für Widgets und Scripts anlegen und sicher nutzen

Mit einem API-Schlüssel liest ein Widget oder Script die Events und andere Daten deines Kanals. Was genau, legst du pro Schlüssel über seine Rechte fest. Bis auf **TTS auslösen** können Schlüssel nur lesen: Sie lösen keine Events aus und fassen keine Einstellungen an.

## Schlüssel erstellen [#schlüssel-erstellen]

<Steps>
<Step>Öffne im Dashboard die Seite **API & SDK**.</Step>
<Step>Klick auf **Neuer Schlüssel** und gib ihm einen Namen, an dem du später erkennst, wo du ihn benutzt (z.B. „StreamElements Sub-Zähler“).</Step>
<Step>Wähl aus, was der Schlüssel darf (siehe [Rechte](#rechte)).</Step>
<Step>Kopier den Schlüssel sofort. Er wird nur dieses eine Mal angezeigt, pixl speichert nur einen Hash davon.</Step>
</Steps>

Schlüssel sehen so aus: `pixl_` gefolgt von 43 Zeichen. In der Liste erkennst du sie an den ersten Zeichen und siehst, wann sie zuletzt benutzt wurden.

## Rechte [#rechte]

Jeder Schlüssel hat eigene Rechte (Scopes). Gib ihm nur, was der Einsatzort wirklich braucht: Ein Sub-Zähler braucht kein TTS, ein TTS-Overlay keine Events.

| Recht | Scope | Erlaubt |
|---|---|---|
| Events lesen | `events:read` | Eventlog abfragen (`pixl.events()`, `pixl.feed()`, `GET /events`) und Twitch-, Stream-, StreamElements- und 7TV-Events live empfangen (`pixl.on()`) |
| StreamElements lesen | `streamelements:read` | Daten aus dem verbundenen StreamElements-Kanal abfragen (`pixl.streamElements()`, `GET /streamelements/…`), z.B. Sitzungswerte, Ranglisten, Songwünsche. Beim Erstellen nicht vorausgewählt |
| TTS abspielen | `tts:read` | Vorgelesene Texte live empfangen und das Audio abrufen (`pixl.tts.player()`, `GET /tts/{id}/audio`) |
| TTS auslösen | `tts:write` | Eigene Texte vorlesen lassen (`pixl.tts.speak()`, `POST /tts`). Verbraucht Credits des Kanals, beim Erstellen nicht vorausgewählt |
| Subs lesen | `subs:read` | Aktuelle Sub-Zahl laut Twitch abfragen (`pixl.subs()`, `GET /subs`) und Änderungen live empfangen (`subs.updated`). Beim Erstellen nicht vorausgewählt |
| Musik lesen | `spotify:read` | Laufenden Spotify-Song abfragen (`pixl.nowPlaying()`, `GET /spotify/now-playing`) und Wechsel live empfangen (`spotify.now_playing`). Braucht das Modul Musik, beim Erstellen nicht vorausgewählt |

`pixl.org()` bzw. `GET /org` geht mit jedem Schlüssel und verrät auch dessen Scopes.

Fehlt ein Recht, antworten HTTP-Aufrufe mit `403` und einer Meldung, welches Recht fehlt. Im Live-Stream kommen die entsprechenden Nachrichten einfach nicht an: Ohne `tts:read` kommen z.B. keine vorgelesenen Texte an.

### Rechte ändern [#rechte-ändern]

Über den Stift neben einem Schlüssel änderst du seine Rechte. Das gilt sofort: HTTP-Aufrufe prüfen bei jeder Anfrage neu, offene Live-Verbindungen werden kurz getrennt und verbinden sich mit den neuen Rechten wieder. Das SDK macht das automatisch, dein Widget merkt höchstens kurz den Status `disconnected`.

## Wer darf Schlüssel verwalten? [#wer-darf-schlüssel-verwalten]

Owner und Admins immer. Andere Mitglieder brauchen das Recht **API-Schlüssel verwalten**, das du unter [Mitglieder](/access#rechte) vergibst.

Schlüssel gehören dem Kanal, nicht der Person, die sie angelegt hat. Verlässt jemand den Kanal, funktionieren seine Schlüssel weiter.

## Schlüssel löschen [#schlüssel-löschen]

Ein gelöschter Schlüssel funktioniert sofort nicht mehr. Offene Verbindungen werden getrennt, das SDK meldet dann den Status `unauthorized` und versucht es nicht erneut.

## Sicherheit [#sicherheit]

<Callout type="warn">
  Wer deinen Schlüssel hat, kann alle Events deines Kanals mitlesen, also z.B. wer wann wie viele Subs oder Bits geschickt hat. Behandle ihn wie ein Passwort.
</Callout>

- Zeig den Code deines Widgets nicht im Stream. Bei StreamElements ist der Schlüssel in einem Feld des Widgets gut aufgehoben, das sieht nur, wer Zugriff auf dein StreamElements-Konto hat.
- Nimm pro Einsatzort einen eigenen Schlüssel. Taucht einer irgendwo auf, wo er nicht hingehört, löschst du nur diesen und der Rest läuft weiter.
- Pro Schlüssel sind 120 Anfragen pro Minute erlaubt. Ein Widget stellt beim Laden ein paar Anfragen und hängt danach nur noch an der Live-Verbindung, das reicht locker.