Die App Schritt für Schritt · Kapitel 33

API-Token für Programme

Mit einem API-Token holen sich Programme wie n8n, eine Karte in nexdeck oder ein Skript von dir Notizen, Aufgaben und Zahlen aus nexlore und schreiben, wenn du es erlaubst, auch etwas hinein. Eine KI brauchst du dafür nicht, und mit den Schlüsseln für MCP aus dem Kapitel KI haben die Token nichts zu tun. Was ein Token kann und warum es so gebaut ist, steht auf der Seite KI, MCP und API.

Der Betreiber schaltet die API ein

API-Token sind ab Werk aus. Bist du Betreiber, öffnest du über das Kontomenü hinter deinem Profilbild rechts oben die Einstellungen, gehst zu Server und dort zu KI, API und Plugins. Auf der Karte „API-Token“ schaltest du Konten dürfen API-Token anlegen ein. Solange der Schalter aus ist, sagt die Karte im Konto, dass der Betreiber API-Token nicht eingeschaltet hat, und es lässt sich kein Token anlegen.

Ein Token anlegen

Öffne Mein Konto und dort den Reiter Verbindungen. Ganz oben steht die Karte „API-Token“, und mit Neues Token legst du eines an.

1. Name

   Gib dem Token einen Namen, an dem du es später wiedererkennst, etwa „n8n zu Hause“ oder „Dashboard“.

2. Stufe

   Lesen holt Bereiche, Notizen, Suchergebnisse, Aufgaben und Zahlen und ändert nichts. Schreiben legt außerdem Notizen an und ändert sie, hängt etwas an, schreibt in die Tagesnotiz und in den Eingang und hakt Aufgaben ab. Nimm die kleinste Stufe, die dein Programm braucht.

3. Bereiche

   Wähle „Alle Bereiche, die ich lesen darf, auch spätere“ oder „Nur diese“ und hake dann die Bereiche an, die das Programm sehen soll.

4. Läuft ab

   Ein Token läuft in 30 Tagen, in 90 Tagen, in einem Jahr oder nie ab. Ab Werk ist „nie“ gewählt.

5. Anlegen

   Nach Anlegen zeigt nexlore das Token, das mit nxa_ beginnt, genau einmal. Darunter stehen eine fertige Kopfzeile für n8n und ein Befehl zum Ausprobieren, beides mit einem Knopf zum Kopieren. Kopier das Token jetzt in dein Programm, denn nexlore behält davon nur eine Prüfsumme.

Account

Das Token in n8n eintragen

In n8n sprichst du nexlore mit dem Knoten HTTP Request an. Die Anmeldung legst du einmal als Zugangsdaten an und nimmst sie danach für jeden Knoten wieder.

1. Anmeldung wählen

   Stell im Knoten Authentication auf „Generic Credential Type“ und Generic Auth Type auf „Header Auth“.

2. Kopfzeile anlegen

   Leg neue Zugangsdaten an, mit Name Authorization und Value Bearer, einem Leerzeichen und dann deinem Token.

3. Adresse eintragen

   Als URL nimmst du die Adresse deines nexlore mit /api/v1 und dem Weg dahinter, etwa https://notes.example.com/api/v1/dashboard. Zum Schreiben stellst du die Methode auf POST und schickst den Körper als JSON.

Generic Auth Type  Header Auth
Name               Authorization
Value              Bearer nxa_...

{"text": "[ ] Paket abholen"}

Das Beispiel schreibt einen Gedanken oben in den Eingang deines Hauptbereichs, mit der Uhrzeit dahinter. Weil die Zeile mit [ ] beginnt, wird daraus eine echte Aufgabe. Ein Ablauf kann so jeden Morgen etwas in die Tagesnotiz schreiben (POST /api/v1/daily) oder Aufgaben aus einem anderen Werkzeug in nexlore sammeln.

Ausprobieren mit curl

Bevor du einen ganzen Ablauf baust, prüfst du das Token am schnellsten in einer Shell. /api/v1/me nennt das Konto, die Stufe und die Bereiche des Tokens, /api/v1/dashboard liefert die Zahlen für ein Dashboard.

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

curl https://notes.example.com/api/v1/dashboard \
  -H "Authorization: Bearer nxa_..."

Kommt 401 mit api_off zurück, hat der Betreiber API-Token ausgeschaltet. Bei token_invalid stimmt das Token nicht, es ist abgelaufen oder gesperrt. Kommt 403 mit origin_refused, hat ein Browser die Anfrage geschickt. Das lässt nexlore nicht zu, weil die API für Programme gedacht ist und nicht für Webseiten.

Eine Karte im Dashboard

Eine Dashboard-Karte wie die für nexdeck zeigt dir die Zahlen deiner Notizen, die fälligen und überfälligen Aufgaben und die zuletzt geänderten Notizen. Dafür reicht ein Token der Stufe Lesen. Willst du aus der Karte heraus Aufgaben abhaken oder schnell etwas in den Eingang schreiben, braucht das Token die Stufe Schreiben. In der Karte trägst du die Adresse deines nexlore und das Token ein, mehr braucht sie nicht. Welche Anfragen eine solche Karte stellt, beschreibt docs/api.md im Repository von nexlore im Abschnitt „A dashboard card“.

Was ein Token in deinen Notizen hinterlässt

Jede Änderung über ein Token wird eine Version der Notiz mit der Quelle „Programm (API)“, und als Autor steht dein Konto darin. Im Reiter Versionen neben der Notiz siehst du also genau, was ein Programm geschrieben hat, und holst bei Bedarf den Stand davor zurück. Löschen, verschieben, umbenennen und teilen kann ein Token nie. Hat sich eine Notiz geändert, seit das Programm sie gelesen hat, oder bearbeitet sie gerade jemand, landet der neue Text in einer Konfliktkopie daneben.

Wenn ein Token abläuft

Eine Woche bevor ein Token abläuft, wird sein Eintrag in der Liste gelb, und du bekommst die Benachrichtigung „API-Token laufen ab“, einmal je Token. Der Anlass ist ab Werk eingeschaltet, und unter Mein Konto, Benachrichtigungen kannst du ihn abschalten. Ist das Token abgelaufen, steht „abgelaufen am …“ dabei, und jede Anfrage damit bekommt 401 mit token_invalid. Leg dann ein neues Token an und tausch es in deinem Programm aus.

Löschen und sperren

Als Betreiber siehst du auf der Karte „API-Token“ unter KI, API und Plugins alle Token des Servers, mit Konto, Stufe, Bereichen und wann sie zuletzt benutzt wurden. Das Token selbst siehst auch du nie, weil nexlore es nirgends gespeichert hat.