API-Token erstellen und aufbewahren

Voraussetzungen

• knowmind-Konto, in jedem Tarif
• Ein sicherer Ablageort für den Token, zum Beispiel ein Passwortmanager

Schritte

1. 1

   Token-Bereich öffnen

   Öffnen Sie im Cockpit API-Tokens (im Menü unter „Anbindung“).

   Ergebnis: Sie sehen Ihre Tokens mit Namen, Rechten und letzter Nutzung, jeweils mit einem Knopf zum Widerrufen.

2. 2

   Token erstellen

   Geben Sie dem Token einen sprechenden Namen wie „Laptop Anna“ oder „GitHub Actions“ und wählen Sie die Rechte: read zum Suchen, write zum Speichern, Hochladen und Verknüpfen, admin für Verwaltungsaufgaben wie den vollständigen Export. Klicken Sie auf „Token erstellen“.

3. 3

   Token sofort kopieren

   Der Token erscheint einmal im Klartext, im Format kmt_…. Kopieren Sie ihn und legen Sie ihn sicher ab. Danach zeigt knowmind nur noch den Anfang des Tokens.

   Ergebnis: Der Token liegt in Ihrem Passwortmanager.

4. 4

   Token einsetzen

   bashkopieren

   # Kommandozeile
   knowmind login --token kmt_…
   
   # Umgebungsvariable (CI, Container)
   export KNOWMIND_TOKEN="kmt_…"
   
   # In einer HTTP-Anfrage
   curl -H "Authorization: Bearer kmt_…" https://knowmind.de/api/health

Prüfung des Ergebnisses

Sicher aufbewahren

• Auf dem eigenen Rechner: Die Kommandozeile legt den Token in ~/.knowmind/config.json ab und beschränkt die Datei auf Ihr Benutzerkonto.
• In CI-Abläufen: als verschlüsselte Variable, die der Ablauf als Umgebungsvariable erhält.
• In Containern und auf Servern: über die Geheimnisverwaltung der Umgebung, zum Beispiel Kubernetes Secrets oder HashiCorp Vault. Tokens stehen in keiner Konfigurationsdatei, die mit dem Code ausgeliefert wird.

# GitHub Actions
env:
  KNOWMIND_TOKEN: ${{ secrets.KNOWMIND_TOKEN }}

knowmind selbst speichert keinen Token im Klartext, nur eine Prüfsumme, aus der sich der Token nicht zurückrechnen lässt.

Token austauschen

1. Neuen Token mit denselben Rechten erstellen.
2. Den neuen Token in der Anwendung oder Geheimnisverwaltung eintragen.
3. Anwendung neu starten und prüfen, dass sie mit dem neuen Token arbeitet.
4. Den alten Token im Cockpit widerrufen.

Ein Token lässt sich nachträglich nicht ändern. Brauchen Sie andere Rechte, erstellen Sie einen neuen Token und widerrufen den alten. Tauschen Sie Tokens in festen Abständen aus, zum Beispiel alle 90 Tage, in regulierten Branchen nach Ihrer internen Vorgabe.

Wenn ein Token in falsche Hände gerät

1. Den Token sofort im Cockpit widerrufen. Der Zugriff endet in diesem Moment.
2. Im Zugriffsprotokoll nachsehen, welche Aufrufe mit dem Token gelaufen sind. Es steht im Cockpit in der Gruppe „Auswertung“ unter „Audit-Log“.
3. Bei Anzeichen für fremde Zugriffe den Vorfall festhalten und prüfen, ob eine Meldung nach Art. 33 DSGVO nötig ist.
4. Unter OAuth-Apps unbekannte Verbindungen entfernen.
5. Einen neuen Token erstellen und in der Anwendung eintragen.

Fehlerbehebung