Konto und Betrieb · Kapitel 22

API-Token

Mit einem API-Token kann ein Programm bei nexdiary nachfragen, etwa eine Karte auf einem Dashboard wie nexdeck. Ein Token liest nur, und nie mehr, als sein Konto lesen darf. Heute kann es sehr wenig: Es sagt, wer du bist und welche Version läuft. An dein Tagebuch kommt es nicht heran.

Der Betreiber schaltet es ein

API-Token sind ab Werk aus. Der Betreiber schaltet sie unter „Einstellungen“, Reiter „API“ mit „Konten dürfen API-Token anlegen“ ein. Schaltet er sie wieder aus, antwortet jedes Token mit einem Fehler, bleibt aber stehen und geht wieder, sobald er einschaltet. In derselben Karte sieht er alle Token mit ihrem Besitzer, nie das Token selbst, und kann eines mit „Sperren“ für immer stilllegen. Im Konto steht es dann als „vom Betreiber gesperrt“.

Ein Token anlegen

1. Zu den Verbindungen

   Über den runden Kontoknopf zu „Mein Konto“, Reiter „Verbindungen“, Karte „API-Token“.

2. „Neues Token“

   Gib ihm unter „Name, damit du es wiedererkennst“ einen Namen, etwa „nexdeck“.

3. „Läuft ab“

   „nie“ ist vorgewählt, sonst „in 30 Tagen“, „in 90 Tagen“ oder „in einem Jahr“.

4. „Anlegen“

   Das Token, beginnend mit nxa_, steht nur jetzt da. Kopier es gleich in dein Programm; nexdiary behält nur eine Prüfsumme. Darunter stehen zum Kopieren die passende Kopfzeile und ein Aufruf mit curl zum Ausprobieren.

Ein Konto kann bis zu 20 Token haben. Die Liste zeigt, wann jedes zuletzt benutzt wurde und wann es abläuft. Ein Token, das du nicht mehr brauchst, löschst du dort.

Was ein Token heute liefert

Jede Anfrage trägt das Token in der Kopfzeile Authorization: Bearer nxa_…, die Antworten sind JSON. Es gibt genau eine Route:

curl -H "Authorization: Bearer nxa_…" https://tagebuch.example.com/api/v1/me

Sie liefert name, display_name, level (immer read) und die version von nexdiary. Mehr gibt es unter /api/v1 noch nicht, auch keinen Weg, Seiten, Notizen oder Fotos zu lesen oder etwas zu schreiben. Was dort steht, bleibt: Neue Felder können dazukommen, umbenannt oder weggenommen wird nichts.

Grenzen und Fehler

• Eine Anfrage aus einer Webseite, also mit einem Origin-Kopf, lehnt nexdiary ab (403, origin_refused). Die Schnittstelle ist für Programme.
• Sind API-Token aus, kommt 401 mit api_off; ist das Token falsch, abgelaufen, gesperrt oder gelöscht, 401 mit token_invalid.
• Mehr als 600 Anfragen pro Minute mit einem Token beantwortet nexdiary mit 429 (slow_down) und sagt mit Retry-After, wann es weitergeht.

Die ganze Beschreibung steht im Projekt unter docs/api.md.