Authentifizierung

Wie Fotovid-API-Schlüssel funktionieren — Format, der Authorization-Header, Scopes, Ablauf und Rotation.

Jede Anfrage an die Fotovid-API wird mit einem API-Schlüssel als Bearer-Token authentifiziert. Schlüssel werden im Web-Dashboard erstellt und verwaltet.

Der Authorization-Header

Sende deinen Schlüssel bei jeder Anfrage im Authorization-Header:

Authorization: Bearer p6_<key_id>:<secret>

Es gibt keinen X-API-Key-Header — Bearer ist das einzige Schema.

Schlüsselformat

Ein vollständiger Schlüssel hat die Form p6_<key_id>:<secret>:

Teil	Beispiel	Hinweise
Präfix	`p6_`	Kennzeichnet einen Fotovid-Schlüssel. Nicht geheim.
Key ID	`01JGXYZ1ABCD...`	Eine 26-stellige ULID. Darf geloggt werden; identifiziert den Schlüssel im Dashboard.
Secret	`a1b2…` (64 hex)	256 Bit Zufall. Der geheime Teil — behandle ihn wie ein Passwort.

Schlüssel erstellen und verwalten

Erstelle Schlüssel im Dashboard unter Account → API Keys. Ein Standardschlüssel wird bei der Registrierung automatisch angelegt.

Der vollständige Schlüssel — inklusive Secret — wird nur einmal bei der Erstellung angezeigt. Kopiere ihn sofort und speichere ihn in einem Secret-Manager. Listen- und Detailansichten zeigen nur ein maskiertes Präfix wie p6_01JGXYZ1...; das Secret ist danach nicht mehr wiederherstellbar. Verloren? Erstelle einen neuen Schlüssel und widerrufe den alten.

Fotovid speichert dein Secret nie im Klartext — nur einen SHA‑256-Hash — daher kann auch der Support einen verlorenen Schlüssel nicht wiederherstellen.

Welche Authentifizierung nutzt welcher Endpunkt?

Die öffentliche Medien-API akzeptiert deinen API-Schlüssel:

Tasks — POST /v1/tasks, GET /v1/tasks, GET /v1/tasks/{id}, POST /v1/tasks/{id}/cancel
Synchron — POST /v1/image/watermark, POST /v1/video/watermark, POST /v1/video/extract-cover, POST /v1/video/trim, POST /v1/audio/trim, POST /v1/video/extract-audio, POST /v1/video/probe

Kontoverwaltung (Schlüssel erstellen, Webhook-Secret rotieren) erfolgt im Dashboard und ist nicht Teil der API-Schlüssel-Oberfläche.

Scopes

Schlüssel tragen grobe Scopes, beide standardmäßig aktiv:

read — GET-Anfragen
write — POST- / PUT- / DELETE-Anfragen

Ablauf und Rotation

Ablauf — optional, 1–365 Tage. Standardmäßig läuft ein Schlüssel nie ab.
Rate-Limit — jeder Schlüssel hat ein eigenes Anfrage-Limit (standardmäßig 60 Anfragen/min). Siehe Rate-Limits.
Widerruf — das Widerrufen eines Schlüssels deaktiviert ihn sofort und ist endgültig. Zum Rotieren: neuen Schlüssel erstellen, ausrollen, dann den alten widerrufen.

Fehler

Ein ungültiger, fehlender, widerrufener oder abgelaufener Schlüssel liefert 401 mit einer generischen Meldung (die API verrät nicht, welcher Fall vorlag):

{
  "type": "https://api.fotovid.co/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "AUTH_INVALID_TOKEN"
}

Siehe Fehler für den vollständigen Vertrag.