API-Authentifizierung

Der programmatische Zugriff auf die nara-API erfolgt über API-Principal-Tokens — organisationsgebundene Bearer-Tokens, die Ihr nara-Betreiber ausstellt. Jeder Principal ist an einen Assistenten und einen Genehmiger gebunden; Runs laufen mit den Fähigkeiten dieses Assistenten.

API-Principal-Tokens

Ein Token identifiziert seinen API-Principal in Ihrer Organisation, nicht einen einzelnen Benutzer. Es gewährt API-Zugriff im Rahmen Ihrer Lizenzstufe; der gebundene Assistent bestimmt, was Runs dürfen.

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 erhalten

Bitten Sie Ihren nara-Betreiber, einen API-Principal für Ihre Organisation anzulegen — mit dem Assistenten, mit dem er laufen soll, und dem Genehmiger seiner Aktionen.
Der Betreiber übergibt Ihnen das Token genau einmal bei der Erstellung. Es kann später nicht erneut abgerufen werden.
Bewahren Sie es in einem Secret-Manager auf und senden Sie es als Bearer-Token.

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/v1/runs/{runId} \
  -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/knowledge/objects \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "typeId": "…", "contents": { "key": "value" } }'

Clerk-Benutzer-JWT

Alternativ zu einem Principal-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/knowledge/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.