Wie erstelle ich einen API-Token?

Ab Tarif Basic

Kurzantwort

Öffne Verwaltung → API-Tokens, klicke „Token erstellen”, vergib einen Namen (z. B. „CI-Pipeline”), wähle die Scopes (read, write oder beides) und optional ein Ablaufdatum. Nach dem Speichern zeigt Notory den Token-Wert (inv_…) genau einmal. Kopiere ihn sofort an einen sicheren Ort. Danach ist nur noch das Präfix sichtbar.

Voraussetzungen

In allen Tarifen verfügbar.

API-Tokens öffnen. Verwaltung → API-Tokens („Persönliche Zugriffstokens für die REST-API. Der Wert wird nur einmal angezeigt.”). Die Liste zeigt Name, Präfix, Scopes, Erstellt und Zuletzt genutzt.

Screenshot ausstehend admin-api-tokens-01 API-Token-Verwaltung mit Token-Liste und Schaltfläche 'Token erstellen'

Die Token-Liste zeigt nur Metadaten, nie den geheimen Wert.
Token anlegen. Klicke „Token erstellen”, vergib einen sprechenden Namen (z. B. „CI-Pipeline”) und wähle die Scopes: read (nur lesen), write (lesen + schreiben); ohne Auswahl gilt der volle Zugriff im Rahmen deiner Rolle. Optional setzt du ein Ablaufdatum.
Wert sofort kopieren. Nach dem Erstellen erscheint: „Neuer Token, jetzt kopieren, er wird nicht erneut angezeigt:”. Kopiere den Wert (inv_…) in deinen Passwort-Manager bzw. das Secret-Management deiner Pipeline.

Screenshot ausstehend admin-api-tokens-02 Einmalige Anzeige des neu erstellten Tokens mit inv_-Präfix und Kopierhinweis

Der Klartext-Wert erscheint genau einmal, danach ist nur noch das Präfix sichtbar.

Testen. Ein erster Aufruf mit dem neuen Token:

curl -H "Authorization: Bearer inv_dein_neuer_token" \
  https://demo.notory.io/api/v1/assets

Auch Tokens selbst lassen sich per API verwalten (z. B. mit einer bestehenden Browser-Sitzung oder einem Alt-Token):

curl -X POST https://demo.notory.io/api/v1/api-tokens \
  -H "Authorization: Bearer inv_bestehender_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI-Pipeline",
    "scopes": "read,write",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Die Antwort (201 Created) enthält das Feld token, allerdings nur dieses eine Mal:

{
  "id": "018f9e33-4d5e-7f66-a071-8b9c0d1e2f30",
  "tenant_id": "3d9b0c12-4e5a-4f88-b1c7-2a9e6d4f0011",
  "user_id": "b7c3d9e1-…",
  "name": "CI-Pipeline",
  "prefix": "inv_9f3kX2mQ",
  "scopes": "read,write",
  "expires_at": "2027-01-01T00:00:00Z",
  "last_used_at": null,
  "is_active": true,
  "created_at": "2026-07-08T10:31:07Z",
  "token": "inv_9f3kX2mQ7Lw…-vollstaendiger-wert-nur-jetzt"
}

Deine Tokens listest du mit GET /api/v1/api-tokens (ohne Geheimwerte, nur Metadaten inkl. prefix und last_used_at).

Mögliche Fehler: 401 (nicht angemeldet), 422 (unbekannter Scope, erlaubt sind nur read und write; leerer Name).

Was passiert dabei?

Sicheres Format, gehashte Ablage. Notory erzeugt inv_ + 32 zufällige URL-sichere Bytes. Gespeichert wird nur der SHA-256-Hash. Der Klartext existiert serverseitig nach der Antwort nicht mehr. Deshalb kann er nie wieder angezeigt werden. Zur Wiedererkennung merkt sich Notory die ersten 12 Zeichen als Präfix.
Scope-Semantik. read erlaubt nur lesende Methoden (GET/HEAD/OPTIONS); write erlaubt Änderungen und schließt Lesen ein. Ohne Scopes gilt der volle Zugriff im Rahmen deiner Rolle (Kompatibilitätsverhalten). Ein unpassender Zugriff endet mit 403 („API token scope does not permit this operation”).
Token ≤ Benutzer. Jede Anfrage mit dem Token läuft unter deinem Konto: Rolle, Berechtigungen und Mandant gelten unverändert; die Mandanten-Isolation (RLS) wird pro Anfrage auf den Token-Mandanten gesetzt. Wird dein Konto deaktiviert, sind alle deine Tokens sofort nutzlos (401).
Ablauf und Nutzungsspur. Nach expires_at antwortet die API mit 401 („Invalid or expired API token”). Bei jeder Nutzung aktualisiert Notory last_used_at. So erkennst du verwaiste oder missbrauchte Tokens.