Token und Scopes

Erstelle begrenzte Zugangsdaten für Skripte und erfahre, welche sensiblen Handlungen damit nie möglich sind.

Ein persönliches Zugriffstoken gibt einem Skript oder Programm begrenzten Zugang zu deinem Budget. Je nach gewähltem Scope kann es Posten, Prognose und Exporte lesen oder auch Budgetdaten ändern, ohne dein Passwort zu verwenden.

Eines erzeugen

Konto → Schnittstellenzugang → Neues Token. Ein Name, mindestens ein Scope und eine Gültigkeit — 30 Tage, 90, ein Jahr oder nie.

Das Token wird einmal gezeigt, beim Anlegen. Gespeichert wird nur ein Hash davon, es kann also nicht noch einmal gezeigt werden; verlierst du es, zieh es zurück und erzeuge ein neues. Das Präfix ebbe_pat_ hilft Secret-Scannern, versehentlich veröffentlichte Tokens zu erkennen.

Schick es als gewöhnliches Bearer-Token:

Authorization: Bearer ebbe_pat_...

Bis zu 50 je Konto, abgelaufene eingerechnet. Zurückziehen wirkt sofort.

Die Angabe „zuletzt benutzt“ ist grob — höchstens stündlich geschrieben —, sie taugt also für „wird dieses Token überhaupt noch benutzt“ und nicht dazu, einzelne Aufrufe nachzuvollziehen.

Die zwei Scopes

Du kannst zwischen zwei Scopes wählen:

• budget:read — das Budget, die Kategorien, die Posten, die Kontostand-Messungen, die Tag-Einstellungen, die Prognose und beide Exporte lesen.
• budget:write — diese Dinge anlegen, ändern und löschen. Es schließt Lesen ein: ein Token mit Schreibrecht kann lesen, du brauchst nicht beide.

Für Auswertungen reicht der Lesezugriff. Den Schreibzugriff solltest du nur vergeben, wenn das Programm dein Budget auch pflegen soll.

Was ein Token nicht kann

Alles zur Identität — Passwort oder Adresse ändern, das Konto löschen, ein weiteres Token erzeugen. Ein Ausweis, der sich seinen eigenen Ersatz ausstellen oder das Konto zerstören könnte, zu dem er gehört, ist gar kein begrenzter Ausweis.

Umfangreiche Änderungen — importieren, das Budget leeren, Demodaten laden oder aufräumen. Diese Funktionen bleiben in der Oberfläche, wo du sie prüfen und bestätigen kannst.

Die Verwaltung. Mit keinem Token-Scope lassen sich Konten oder die Konfiguration des Dienstes verwalten.

Anfragelimits

Die Limits werden je Token gezählt. Für Sicherungen solltest du den Export nach einem Zeitplan abrufen, nicht in einer Schleife.

Die vollständige Referenz

Die aktuelle Endpunktliste findest du unter /api/docs. Ebbe erzeugt diese Referenz direkt aus den Routen, die für Tokens verfügbar sind. Über Authorize kannst du ein Token einsetzen und einen Aufruf direkt auf der Seite ausprobieren.

/api/openapi.json ist dasselbe als maschinenlesbares Dokument.

Wenn etwas abgelehnt wird

Eine Ablehnung nennt einen Code statt eines Satzes, damit ein Programm darauf verzweigen und ein Mensch ihn nachschlagen kann. 401 heißt, das Token ist unbekannt, abgelaufen oder zurückgezogen; 403 heißt, es ist gültig, aber der Scope fehlt; 409 heißt, eine Obergrenze ist erreicht, und die Antwort nennt welche. Siehe Grenzen.