Authentifizierung

Jede Anfrage trägt einen API-Schlüssel. Schlüssel werden in der App unter API-Schlüssel → Schlüssel erstellen angelegt, von Inhabern und Admins der Organisation. Ein Schlüssel gehört zu genau einem Workspace, und sein Geheimnis wird einmal angezeigt, beim Anlegen; danach zeigt die App nur noch seine ersten Zeichen (das Präfix).

Authorization: Bearer ff_live_3f9c...

X-API-Key: ff_live_3f9c... wird ebenfalls akzeptiert; sendet eine Anfrage beides, zählt Authorization. Ein Schlüssel ist ff_live_ oder ff_test_, gefolgt von 43 Buchstaben und Ziffern.

Wenn ein Schlüssel abgelehnt wird

Antwort	Grund
401 unauthorized	Es wurde kein Schlüssel gesendet (die Antwort trägt WWW-Authenticate: Bearer), der Schlüssel hat nicht das Format ff_live_…/ff_test_…, oder er ist unbekannt oder widerrufen. detail sagt, was zutrifft.
403 forbidden	Dem Schlüssel fehlt der Scope, den der Endpunkt braucht (This API key lacks the "template:write" scope).
403 forbidden	Die Anfrage kommt von einer Webseite (sie hat einen Origin-Header). Schlüssel sind für Server; siehe Aus dem Browser.
403 forbidden	Der Plan enthält die Funktion nicht; das Problem nennt sie in feature (post_processing, office, einvoice, channels …). Siehe Plan-Limits.

Test- und Live-Schlüssel

Das Präfix zeigt die Umgebung. Sie wählen sie beim Anlegen des Schlüssels (Test oder Live).

	ff_live_…	ff_test_…
Verwenden für	Produktion	Entwicklung, CI, Staging, das Dev-Kit
Einheiten	Werden gegen den Plan gezählt (Einheiten)	Werden nicht gezählt. Test-E-Rechnungen sind stattdessen auf eine Anzahl pro Tag begrenzt
Wenn die Einheiten des Free-Plans aufgebraucht sind	Renderings stoppen mit 402 quota_exceeded	Renderings laufen weiter
Aufbewahrung der Ausgaben	Die Aufbewahrungsfrist des Plans oder die kürzere des Workspace (Aufbewahrung)	Höchstens 24 Stunden
Testmarkierung auf der Datei	Nie	Im Free-Plan auf jeder Testdatei; in jedem Plan auf einer Test-E-Rechnung
Deduplizierung	Ja	Nein, jede Anfrage rendert
version: "latest" (der Entwurf)	Wird mit 400 invalid_request abgelehnt	Erlaubt
Word- und PowerPoint-Vorlagen	Ab dem Starter-Plan	Im Free-Plan nur das PDF (403 test_output_unavailable für docx und pptx)
Rate-Limit	Die Anfragen pro Sekunde des Plans	Derselbe Bucket wie für Live-Schlüssel, im Free-Plan zusätzlich 30 Anfragen pro Minute
Webhook-Ereignisse	Gehen an jeden Endpunkt, der live in seinen environments hat	Gehen an jeden Endpunkt, der test in seinen environments hat (beides ist der Standard)

Alles andere ist identisch: dieselben Endpunkte, dieselben Vorlagen, dieselbe Ausgabe. Für den Wechsel in die Produktion tauschen Sie nur den Schlüssel aus.

Scopes

Ein Schlüssel kann nur, was seine Scopes erlauben. Wählen Sie sie beim Anlegen des Schlüssels; ein ✓ markiert die, die der Dialog standardmäßig ankreuzt.

Scope	Erlaubt	Standard
render:create	POST /renders, POST /renders/batch, die PDF-Tools POST /pdf/merge, /pdf/protect, /pdf/watermark und /pdf/convert, die Kompatibilitätsendpunkte	✓
render:read	GET /renders, GET /renders/{id}, GET /renders/{id}/result, GET /jobs/{id}, POST /pdf/info	✓
render:input	GET /renders/{id}/input, die aufbewahrte Anfrage eines Renderings (formfeed renders pull); jeder Lesezugriff wird protokolliert. Siehe Ein fehlgeschlagenes Rendering nachstellen
template:read	Vorlagen, Versionen, Dateien, Schemas und Channels lesen, POST /templates/{id}/validate, Brand Kit und geteilte Partials lesen (formfeed templates pull)	✓
template:write	Vorlagen anlegen, ändern, veröffentlichen und archivieren, Release Channels verschieben, geteilte Partials schreiben (formfeed templates push)
webhook:manage	Webhook-Endpunkte verwalten (nötig für die Trigger der No-Code-Integrationen), Ereignisse erneut an sie senden und Live-Ereignisse mit formfeed listen --live
webhook:listen	Sitzungen von formfeed listen und Ereignisse erneut an sie senden. Siehe Webhooks lokal entwickeln
account:read	GET /account, GET /usage (formfeed whoami)	✓
file:read	GET /files, GET /files/{id} (die Dateibibliothek des Workspace)
file:write	POST /files (Hochladen in die Bibliothek)
file:delete	DELETE /renders/{id}/outputs, DELETE /files/{id}
workspace:delete	DELETE /workspaces/{id} für jeden Workspace der Organisation des Schlüssels, auch seinen eigenen (formfeed workspaces delete). Nie Teil eines Standards oder eines CLI-Anmeldeschlüssels

Ein Write-Scope bringt seinen Read-Scope mit: Wer im Dialog render:create ankreuzt, kreuzt auch render:read an, template:write kreuzt template:read an und file:write kreuzt file:read an, weil Schreiben das Objekt zurückgibt und ein Schlüssel lesen können soll, was er geschrieben hat.

Geben Sie jeder Integration einen eigenen Schlüssel mit den kleinstmöglichen Scopes: Ein Backend, das nur rendert, braucht render:create und render:read; der Schlüssel in Ihrem CI-Schritt zum Veröffentlichen braucht template:write.

Schlüssel sicher aufbewahren

• Halten Sie Schlüssel auf dem Server. Die API lehnt einen Schlüssel ab, der von einer Webseite gesendet wird (Aus dem Browser), und ein Schlüssel in einer mobilen App oder einem Browser-Bundle ist ohnehin öffentlich: Jeder, der ihn findet, kann auf Ihre Kosten rendern.
• Speichern Sie Schlüssel in Ihrem Secret-Manager oder in der Umgebung (FORMFEED_API_KEY), nie im Repository.
• Benennen Sie Schlüssel nach ihrem Einsatzort (billing-service-prod, github-actions). Die Liste unter API-Schlüssel zeigt, wann jeder Schlüssel Zuletzt genutzt wurde. Ein ungenutzter Schlüssel fällt so leicht auf und lässt sich widerrufen.
• Rotieren Sie ohne Ausfallzeit: Legen Sie den neuen Schlüssel an, bringen Sie ihn in Betrieb, prüfen Sie, dass sich die Angabe Zuletzt genutzt des alten Schlüssels nicht mehr ändert, und widerrufen Sie dann den alten Schlüssel (Schlüssel widerrufen). Ein widerrufener Schlüssel funktioniert innerhalb einer Minute nicht mehr, weil die API die Angaben eines Schlüssels bis zu 60 Sekunden vorhält.

Die App und KI-Agenten

Die App und KI-Agenten, die über den MCP-Server mit einer Anmeldung bei Formfeed verbunden sind, verwenden keine API-Schlüssel. Sie senden das Sitzungstoken des Mitglieds als Authorization: Bearer …, und die App nennt den Workspace in X-Formfeed-Workspace. Ein solches Token kann, was die Rolle des Mitglieds erlaubt. Das Token eines Agenten ist weiter eingeschränkt, auf render:create, render:read, template:read und account:read: Ein Agent kann weder veröffentlichen, löschen, Webhooks verwalten noch einen Entwurf (latest) rendern, gleich welche Rolle das Mitglied hat. Erlaubt das Mitglied es diesem Agenten und darf seine Rolle Vorlagen bearbeiten, kann der Agent außerdem Vorlagen als Entwürfe speichern (POST /templates und POST /templates/{id}/versions ohne publish; siehe Vorlagen-Entwürfe). Nutzt das Mitglied die Zwei-Faktor-Authentifizierung, arbeitet ein Agent erst, nachdem das Mitglied ihn in Formfeed bestätigt hat. Für Ihre eigenen Integrationen brauchen Sie nichts davon: Verwenden Sie einen API-Schlüssel.

CLI-Anmeldung

formfeed login verwendet einen Geräte-Flow statt eines eingefügten Schlüssels: Die CLI zeigt einen Code, Sie bestätigen ihn im Browser unter app.formfeed.dev/device und wählen einen Workspace, und die CLI erhält einen Live-Schlüssel (ff_live_…) mit dem Namen Formfeed CLI on <machine> und den Scopes Ihrer Rolle in der Organisation. Renderings mit ihm sind Live-Renderings und zählen gegen die Einheiten des Plans; wenn Sie nur ausprobieren, melden Sie sich mit formfeed login --api-key ff_test_… und einem Test-Schlüssel an.

Rolle	Scopes des CLI-Schlüssels
Betrachter	render:read, template:read, account:read, file:read
Editor	die des Betrachters, dazu render:create, template:write, file:write, render:input, webhook:listen
Admin und Inhaber	die des Editors, dazu webhook:manage und file:delete

Der Schlüssel erhält nie workspace:delete. Er erscheint wie jeder andere unter API-Schlüssel und lässt sich dort widerrufen. formfeed logout entfernt den Schlüssel nur von Ihrem Rechner; gültig bleibt er, bis Sie ihn in der App widerrufen. In der CI setzen Sie stattdessen FORMFEED_API_KEY. Siehe CLI-Installation.