Authentifizierung

Jeder Request an /api/v1 benötigt einen API-Key. Session-Cookies der Web-App werden auf Public-API-Routen nicht akzeptiert.

Verfügbarkeit

Die Public API erfordert ein aktives Pro-Abonnement. Ohne API-Zugang ist das Erstellen von API-Keys deaktiviert. Zusätzlich prüft jeder Request die aktuelle Berechtigung des Teams. Ein gültiger API-Key eines Teams ohne Zugang erhält 403 plan_required.

API-Key erstellen und speichern

Öffne Einstellungen → API-Schlüssel, wähle einen Namen und vergib einen oder beide Scopes. Das Secret beginnt mit na_ und wird einmal angezeigt. New Archive speichert nur den Hash. Ein verlorener API-Key kann daher nicht wiederhergestellt werden; widerrufe ihn und erstelle einen neuen.

Speichere den API-Key außerhalb der Versionsverwaltung:

bash
export NEW_ARCHIVE_URL="https://your-host"
export NEW_ARCHIVE_API_KEY="na_your_key"

API-Key mitsenden

Verwende bei jedem Request das HTTP-Bearer-Schema:

http
Authorization: Bearer na_your_key
bash
curl --fail-with-body \
  "$NEW_ARCHIVE_URL/api/v1/files/0198c9a0-7d3e-7c41-b7a2-3f9d1c2e4a5b" \
  -H "Authorization: Bearer $NEW_ARCHIVE_API_KEY"

Ein fehlender, falsch formatierter, abgelaufener oder widerrufener API-Key führt zu 401 unauthorized. Ein gültiger API-Key ohne den erforderlichen Scope führt zu 403 forbidden.

Scopes und Rollenberechtigungen

ScopeGewährt
uploadDateien hochladen sowie Metadaten und Processing-Status lesen.
searchDie Bibliothek durchsuchen sowie Metadaten und Processing-Status lesen.

Scopes lassen sich nach der Erstellung nicht ändern. Erstelle einen neuen API-Key, wenn sich der Zugriff ändern soll.

Ein API-Key handelt als das Mitglied, das ihn erstellt hat, und ist auf dessen Team beschränkt. Uploads werden diesem Mitglied zugeordnet. Der Scope upload allein reicht nicht: Die aktuelle Teamrolle des Mitglieds muss auch files.upload erlauben. Ein Widerruf wirkt sofort.

Rate Limits

Jeder API-Key darf 120 Requests in einem 60-Sekunden-Fenster senden. Ein abgewiesener Request liefert 429 rate_limited; der Header Retry-After kann die Wartezeit in Sekunden enthalten.

http
HTTP/2 429
content-type: application/json
retry-after: 42

{"error":{"code":"rate_limited","message":"Rate limit exceeded"}}

API-Keys schützen

  • Speichere API-Keys in einem Secret Manager oder in Umgebungsvariablen, niemals in Frontend-Code oder einem Repository.
  • Gib jeder Integration einen eigenen, möglichst eng begrenzten API-Key.
  • Widerrufe ungenutzte oder offengelegte API-Keys sofort.
  • Behandle Request-Logs vorsichtig: Der Header Authorization enthält das vollständige Secret.
ZurückPublic APIWeiterDateien hochladen