Authentifizierung

Jede Anfrage an die API trägt genau einen API-Schlüssel im Authorization-Header:

Authorization: Bearer sk-popnow-3f9c0a…

Einen anderen Weg gibt es nicht: Schlüssel im Query-String der URL werden nie akzeptiert, und deine Anmeldung auf popnow.ai gilt für die API nicht.

Eine Ausnahme: Die OpenAI-kompatiblen Routen unter /v1 lesen den Schlüssel auch aus dem Header x-api-key, damit OpenAI-Clients unverändert funktionieren. Die nativen /api/v1-Routen lesen nur Authorization.

So sieht ein Schlüssel aus

Ein Schlüssel besteht aus sk-popnow- und 48 kleingeschriebenen Hexadezimalzeichen. Nach dem Erstellen zeigt die API-Konsole nur noch die ersten Zeichen – ein verlorener Schlüssel lässt sich nicht wiederherstellen. Erstelle einfach einen neuen.

Schlüssel erstellen

1. Melde dich auf popnow.ai an und öffne die API-Konsole.
2. Wähle Create key und gib ihm einen Namen, der sagt, wo er eingesetzt wird, etwa production-backend.
3. Kopiere den Schlüssel sofort. Er wird nur einmal angezeigt.

Du kannst mehrere Schlüssel gleichzeitig haben. Einer pro Umgebung oder Dienst ist eine gute Gewohnheit, denn dann lässt sich einer widerrufen, ohne die anderen anzufassen. Alle Schlüssel zahlen aus demselben Credit-Guthaben.

Wo der Schlüssel hingehört

• In eine Umgebungsvariable oder den Secret-Speicher deiner Plattform (POPNOW_API_KEY), nicht in den Quellcode.
• Niemals in einen Browser, eine Mobile-App oder anderen Code, der auf fremden Geräten läuft. Wer den Schlüssel lesen kann, kann deine Credits ausgeben. Schalte deinen eigenen Server dazwischen und lass ihn PopNow aufrufen.
• Nicht in Logs. Wenn du Request-Header protokollierst, entferne vorher Authorization.

Was ein Schlüssel darf

Jeder Schlüssel kann in der API-Konsole eigene Grenzen bekommen:

Standardmäßig hat ein Schlüssel weder Einschränkungen noch Limits. Gib Produktionsschlüsseln nur so viel, wie sie wirklich brauchen.

Tasks gehören dem Schlüssel, der sie erstellt hat

recordInfo, retry, purge, die Task-Liste und die Nutzung sehen nur Tasks, die mit demselben Schlüssel erstellt wurden. Ein Task eines anderen Schlüssels deines Kontos antwortet mit 404 – genau wie ein Task, den es nicht gibt. Generierungen, die du auf der Website startest, sieht ebenfalls kein Schlüssel. Für den Blick aufs ganze Konto nimm die API-Konsole.

Rotation

So tauschst du einen Schlüssel ohne Ausfall:

1. Neuen Schlüssel erstellen.
2. Ihn überall ausrollen, wo der alte verwendet wurde.
3. In der Konsole beobachten, dass die letzte Nutzung des alten Schlüssels stehen bleibt.
4. Den alten Schlüssel widerrufen.

Wenn ein Schlüssel geleakt ist

1. Sofort widerrufen – in der API-Konsole. Das gilt ab der nächsten Anfrage.
2. Ersatz erstellen und ausrollen.
3. Prüfen, wofür er benutzt wurde: Logs und Nutzung in der Konsole zeigen jeden Task, den der Schlüssel erstellt hat.
4. Den Ersatz absichern – mit IP-Allowlist und Ausgabelimit.

Wenn du Ausgaben siehst, die nicht von dir stammen, kontaktiere den Support.

So sieht ein Fehler aus

Alle drei Authentifizierungsprobleme liefern HTTP 401 mit code: 401; msg unterscheidet sie:

Auch ein gültiger Schlüssel kann mit 403 abgewiesen werden – etwa wenn die E-Mail-Adresse des Kontos noch nicht bestätigt ist (40310). Siehe Fehler.