API-Authentifizierung und Token
Auf dieser Seite
Alle dokumentierten Endpunkte unter /api/v1 benötigen ein Bearer-Token. Die
einzige Ausnahme ist der öffentliche Statusendpunkt /health.
Authorization: Bearer <API-TOKEN>
Vorsicht
Das Token wird einmal angezeigt. Es lässt sich nicht wiederherstellen, sondern nur ersetzen. Bewahre es wie ein Passwort in der Umgebungskonfiguration deiner Anwendung auf – niemals im Quelltext oder in einem öffentlichen Frontend.
Zugriff auf Feeds begrenzen#
Jedes Token gehört zu genau einer Verknüpfung, und die hat einen Feed-Umfang: entweder alle Feeds deines Kontos oder eine ausdrückliche Auswahl. Für nicht freigegebene Feeds kann die API mit 404 antworten.
Ein Token gewährt ausschließlich Lesezugriff auf Feeds. Es kann keine Feeds ändern, keine Konten verbinden und nichts an deinem Abo tun.
Hinweis
Die API ist für serverseitige Anwendungen vorgesehen. Für eine direkte Einbindung auf Websites verwendest du das Web-Widget.
Client-Version übermitteln#
Mit X-Feedivo-Client kannst du optional den Namen und die Version deiner
Anwendung übermitteln.
X-Feedivo-Client: meineapp/1.4.0
Erlaubt sind bis zu 40 Zeichen aus Buchstaben, Ziffern und . _ + - /. Der Wert
erscheint auf der Seite deiner Verknüpfung. Bei einer Rückfrage ist damit klar,
welche Version angefragt hat.
Token ersetzen und rotieren#
Ein neues Token für dieselbe Verknüpfung erzeugst du in der App; das alte verfällt sofort. Aktualisiere deshalb zuerst die vorgesehene Anwendung und prüfe anschließend einen normalen API-Abruf.
Wichtige Antwort-Header#
| Kopfzeile | Bedeutung |
|---|---|
ETag |
Kennung des Inhalts; als If-None-Match zurücksenden für 304 |
X-RateLimit-Limit |
Anfragen je Minute nach Tarif |
X-RateLimit-Remaining |
Rest im laufenden Fenster |
X-RateLimit-Reset |
Zeitpunkt, zu dem das Fenster neu beginnt |
Cache-Control |
Post-Listen private, max-age=60, Feed-Metadaten private, no-cache (behalten erlaubt, aber vor jeder Nutzung nachfragen), /me private, no-store |
Einheitliches Fehlerformat#
Fehler nutzen denselben Umschlag wie Erfolge, mit data und meta auf null:
{
"data": null,
"meta": null,
"errors": [{ "status": 403, "code": "entitlement_paused", "message": "…" }]
}
Verzweige immer über code, nie über message — die Meldung ist deutscher
Fließtext und darf sich ändern.
code |
Status | Bedeutung |
|---|---|---|
invalid_token |
401 | Token fehlt oder gilt nicht mehr — ein neues hilft |
entitlement_paused |
403 | Tarif deckt Verknüpfung oder Feed gerade nicht; ein neues Token bringt nichts |
feed_not_found |
404 | Feed nicht gefunden oder für diese Verknüpfung nicht verfügbar |
post_not_found |
404 | Post gibt es nicht mehr, oder dieser Feed liefert ihn nicht |
invalid_parameter |
422 | Ein Query-Parameter ist unlesbar; die Meldung nennt welcher |
rate_limited |
429 | Zu viele Anfragen — Retry-After abwarten |
server_error |
5xx | Unerwarteter Fehler; der Aufruf darf wiederholt werden |
Bei Verbindungsfehlern, 5xx oder unlesbaren Antworten behältst du deine lokale Kopie. Mehr dazu steht im API-Schnellstart.
Frage nicht beantwortet? Schreib uns — wir ergänzen die Seite.