API-Authentifizierung

Der programmatische Zugriff auf die nara-API erfolgt über Server-Tokens — organisationsgebundene Bearer-Tokens, die Administratoren in der Webapp erzeugen.

Server-Tokens

Ein Server-Token identifiziert Ihre Organisation, nicht einen einzelnen Benutzer. Es gewährt vollen API-Zugriff im Rahmen Ihrer Lizenzstufe; es gibt keine tokenspezifischen Berechtigungsumfänge (Scopes).

Tokens haben das Format nara_sa_ gefolgt von einem zufälligen Suffix, zum Beispiel:

nara_sa_9fK2mQ7xR4tW8vLpN3jH6bC1dY5sA0eZgUoIiT-uXnM

nara speichert ausschließlich einen SHA-256-Hash jedes Tokens. Der vollständige Wert wird nur einmal bei der Erzeugung angezeigt; danach sind nur die ersten Zeichen als Präfix sichtbar, damit Sie das Token identifizieren können. Kopieren Sie das Token sofort und bewahren Sie es in einem Secret-Manager auf.

Token erzeugen

Öffnen Sie Admin > Settings.
Wählen Sie im Bereich Server token die Option Generate (bzw. Regenerate, um ein bestehendes Token zu ersetzen).
Kopieren Sie das angezeigte Token. Es kann später nicht erneut abgerufen werden.

Das Erzeugen und Verwalten von Tokens erfordert die Berechtigung serviceAccount.manage, die in der integrierten Rolle Admin standardmäßig enthalten ist.

Token-Arten

Art	Ablauf	Verhalten
Long-lived	Optional	Gültig bis zum Widerruf oder Ablauf
Short-lived	Erforderlich (`expiresAt`)	Gültig bis zum Ablaufzeitpunkt
Single-use	Erforderlich (`expiresAt`)	Wird nach der ersten Anfrage automatisch widerrufen

Widerrufen und Rotieren

Sie können ein Token jederzeit widerrufen, um es sofort ungültig zu machen. Zum Rotieren erzeugen Sie ein neues Token, aktualisieren Ihre Clients und widerrufen anschließend das alte Token. Jedes Token speichert bei jeder Anfrage einen lastUsedAt-Zeitstempel, sodass Sie veraltete oder unerwartete Nutzung vor dem Widerruf erkennen können.

Anfragen authentifizieren

Senden Sie das Token bei jeder Anfrage im Authorization-Header:

curl https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer nara_sa_..."

Schreibende Anfragen (POST, PUT, PATCH) müssen zusätzlich Content-Type: application/json setzen:

curl -X POST https://app.nara.de/api/memory/objects \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "typeId": "…", "contents": { "key": "value" } }'

Clerk-Benutzer-JWT

Alternativ zu einem Server-Token können Sie sich als Benutzer mit einem von Clerk ausgestellten JWT authentifizieren. Da ein Benutzer mehreren Organisationen angehören kann, wählen Sie die Organisation über den Header Clerk-Organization-Id aus:

curl https://app.nara.de/api/memory/types \
  -H "Authorization: Bearer <clerk-jwt>" \
  -H "Clerk-Organization-Id: <organization-id>"

Fehlercodes

Status	Bedeutung
`400`	Ungültiger Anfrage-Body oder ungültige Parameter
`401`	Fehlendes, ungültiges, abgelaufenes oder widerrufenes Token
`402`	Unzureichende Credits für die Operation
`403`	Berechtigung verweigert (z. B. Admin erforderlich)
`404`	Ressource nicht gefunden
`500`	Interner Serverfehler

Sicherheitspraktiken

Committen Sie Tokens niemals in die Versionsverwaltung. Bewahren Sie sie in Umgebungsvariablen oder einem Secret-Manager auf.
Rotieren Sie Tokens regelmäßig und unmittelbar nach jedem Verdacht auf Offenlegung.
Bevorzugen Sie Short-lived- oder Single-use-Tokens für selten laufende Automatisierungen.
Prüfen Sie lastUsedAt-Zeitstempel, um ungenutzte Tokens zu erkennen und zu widerrufen.

Die verfügbaren Endpunkte finden Sie in der API-Referenz.