API-Schlüssel und Scopes

Jede Anfrage an die Sursa-API erfolgt mit einem API-Schlüssel Ihrer Organisation. Ein Schlüssel gehört der Organisation, nicht einer Person: Er funktioniert weiter, wenn die Person, die ihn erstellt hat, das Unternehmen verlässt, und was er darf, wird am Schlüssel selbst festgelegt.

Was ein Schlüssel darf

Drei Einstellungen eines Schlüssels bestimmen, was eine Anfrage damit sehen und ändern kann. Jede davon schränkt die anderen nur weiter ein.

Einstellung	Was sie steuert
Rolle	`admin`, `editor`, `verifier` oder `viewer` – dieselben Rollen, die auch Personen haben. Der Schlüssel darf, was eine Person mit dieser Rolle darf.
Scopes	Welche Teile der API der Schlüssel aufrufen darf, zum Beispiel `cards:read` oder `webhooks:manage`. Siehe Scopes von Schlüsseln.
Datenprofil	Optional. Beschränkt den Schlüssel auf die Wissenskategorien, die das Profil erlaubt – wie bei einer Person mit diesem Profil.

Ein Schlüssel kann außerdem auf einzelne Sammlungen beschränkt werden und ein Ablaufdatum erhalten. Eine Anfrage außerhalb dieser Grenzen schlägt fehl: Ein fehlender Scope ergibt 403 mit dem Code api_keys.scope, und ein Objekt, das der Schlüssel nicht sehen kann, ergibt 404 – genau so, als gäbe es das Objekt nicht.

Geben Sie jeder Integration einen eigenen Schlüssel mit der engsten Rolle und den Scopes, die sie braucht. Ein Synchronisierungsjob, der nur Dokumente schreibt, braucht kein admin; ein Berichtsjob braucht keine Schreib-Scopes.

Schlüssel erstellen

Schlüssel legen Administratorinnen und Administratoren der Organisation in Sursa unter Administration → API keys an oder mit POST /v1/api-keys – mit einem Schlüssel oder einer Sitzung mit der Rolle admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Die Antwort enthält den Wert des Schlüssels in key. Er wird nur einmal angezeigt: Sursa speichert nur einen Hash davon und kann ihn nicht erneut anzeigen. Ein Schlüssel besteht aus kb_ und 43 weiteren Zeichen; die ersten Zeichen (prefix) erscheinen in der Liste der Schlüssel, damit Sie Schlüssel unterscheiden können.

Ohne scopes erhält der Schlüssel die Scopes seiner Rolle. Übergeben Sie scopes, um ihn weiter einzuschränken. Ohne expires_at läuft der Schlüssel nicht ab.

Schlüssel geheim halten

Bewahren Sie Schlüssel in einem Secret-Manager oder in Umgebungsvariablen Ihres Dienstes auf, niemals im Quellcode.
Verwenden Sie Schlüssel nur von Ihren Servern aus. Sursa nimmt Anfragen aus Browsern an (CORS ist offen), aber ein Schlüssel in einer Webseite ist für alle sichtbar, die die Seite öffnen.
Senden Sie einen Schlüssel niemals in einer URL, sondern nur im Header Authorization.
Gelangt ein Schlüssel nach außen, widerrufen Sie ihn sofort und erstellen Sie einen neuen.

Schlüssel prüfen

GET /v1/me gibt den Schlüssel, seine Rolle, die wirksamen Scopes, das Datenprofil, das Ablaufdatum und das Ratenlimit zurück. Die Anfrage funktioniert mit jedem gültigen Schlüssel, unabhängig von seinen Scopes. Verwenden Sie sie deshalb als Verbindungstest Ihrer Integration und wenn Sie einem 403 nachgehen.

Schlüssel rotieren

Bei der Rotation wird ein Schlüssel ersetzt, ohne die Integration anzuhalten. Am schnellsten geht es, wenn Sie den Schlüssel selbst rotieren: POST /v1/api-keys/{key_id}/roll stellt einen neuen Wert für denselben Schlüssel aus, mit derselben Rolle, denselben Scopes, denselben Sammlungen und demselben Ablaufdatum. Der bisherige Wert funktioniert noch overlap_hours lang (standardmäßig 24 Stunden, höchstens 168), sodass Sie den neuen Wert in der Zwischenzeit hinterlegen können; POST /v1/api-keys/{key_id}/revoke-previous beendet die Überlappung vorzeitig.

Um einen Schlüssel stattdessen durch einen anderen zu ersetzen:

Erstellen Sie einen neuen Schlüssel mit derselben Rolle, denselben Scopes und demselben Datenprofil.
Hinterlegen Sie den neuen Schlüssel in Ihrer Integration.
Beobachten Sie den alten Schlüssel unter Administration → API keys (oder last_used in GET /v1/api-keys), bis er nicht mehr verwendet wird.
Widerrufen Sie den alten Schlüssel.

Versehen Sie Schlüssel mit einem Ablaufdatum und rotieren Sie sie rechtzeitig davor. Sursa warnt die Administratorinnen und Administratoren der Organisation, bevor ein Schlüssel abläuft; ein abgelaufener Schlüssel ergibt 401 mit dem Code api_keys.expired.

Schlüssel widerrufen

Widerrufen Sie einen Schlüssel unter Administration → API keys oder mit DELETE /v1/api-keys/{key_id}. Der Widerruf wirkt innerhalb von Sekunden auf allen API-Servern. Anfragen mit einem widerrufenen Schlüssel ergeben 401 mit dem Code auth.not_authenticated.

Schlüssel einer benutzerdefinierten Quelle

Eine benutzerdefinierte Quelle hat eine eigene Art von Schlüssel. Er beginnt mit kbsrc_, kann nur Dokumente in genau diese Quelle schreiben und weder etwas lesen noch durchsuchen. Er ist der sicherste Schlüssel, den Sie einer Integrationsplattform wie Zapier geben können. Erstellen Sie ihn auf der Seite der Quelle unter API keys oder mit POST /v1/sources/{source_id}/push-keys.

Wenn Schlüssel nicht verfügbar sind

API-Schlüssel sind Teil des Tarifs der Organisation. Enthält der Tarif sie nicht, ergeben das Erstellen eines Schlüssels und jede Anfrage mit einem Schlüssel 403 mit dem Code api_keys.feature_disabled.