Authentifizierung

Jede Anfrage an die Sursa-API trägt einen API-Schlüssel oder das OAuth-Zugriffstoken einer Anwendung im Header Authorization:

Authorization: Bearer kb_3f9c…

Der Schlüssel identifiziert die Organisation und legt fest, was die Anfrage sehen und ändern darf: seine Rolle, seine Scopes, sein Datenprofil und seine Sammlungen. Unter der API-Adresse gibt es keine Sitzungen und keine Cookies. Jede Anfrage wird für sich authentifiziert, sodass Sie mit demselben Schlüssel Anfragen parallel und von mehreren Servern senden können.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Ältere Integrationen senden den Schlüssel unter Umständen stattdessen im Header X-API-Key. Er wird weiterhin akzeptiert, neuer Code sollte aber Authorization: Bearer verwenden.

Arten von Anmeldedaten

Anmeldedaten	Aussehen	Wo sie gelten
API-Schlüssel der Organisation	`kb_…`	Jeder Endpunkt der API, im Rahmen von Rolle, Scopes, Datenprofil und Sammlungen des Schlüssels.
Schlüssel einer benutzerdefinierten Quelle	`kbsrc_…`	Nur die Push-Endpunkte der eigenen benutzerdefinierten Quelle (`/v1/push/sources/{source_id}/…`).
OAuth-Zugriffstoken	`kbat_…`	Die Endpunkte der API-Referenz, im Rahmen der Scopes des Tokens. Ein Token von `POST /oauth/token` mit einem Autorisierungscode handelt im Namen der mitarbeitenden Person, die zugestimmt hat; ein `client_credentials`-Token handelt wie ein API-Schlüssel für die Organisation. Es gilt 1 Stunde lang.

Alle diese Anmeldedaten werden auf dieselbe Weise gesendet. Ein Schlüssel einer benutzerdefinierten Quelle kann außerhalb seiner Quelle nichts lesen, durchsuchen oder ändern. Verwenden Sie ihn dort, wo der Schlüssel bei einem Drittanbieter gespeichert wird, etwa bei einer Integrationsplattform.

Authentifizierungsfehler

Status und Code	Bedeutung	Was zu tun ist
`401` `auth.not_authenticated`	Kein Schlüssel, ein falsch eingegebener oder ein widerrufener Schlüssel.	Prüfen Sie den Header und den Wert des Schlüssels.
`401` `api_keys.expired`	Das Ablaufdatum des Schlüssels ist überschritten.	Erstellen Sie einen neuen Schlüssel und ersetzen Sie den alten.
`401` `sources.push_key_invalid`	Ein Schlüssel einer benutzerdefinierten Quelle ist falsch, widerrufen oder gehört zu einer anderen Quelle.	Prüfen Sie den Schlüssel und die Quell-ID im Pfad.
`401` `oauth.token_expired`	Das OAuth-Zugriffstoken ist abgelaufen.	Holen Sie mit dem Refresh-Token ein neues.
`403` `api_keys.scope`	Der Schlüssel hat keinen Scope für diese Operation.	Fügen Sie den Scope hinzu oder verwenden Sie einen Schlüssel, der ihn hat.
`403` `api_keys.feature_disabled`	Der Tarif der Organisation enthält keine API-Schlüssel.	Wenden Sie sich an die Administration der Organisation.
`403` `api_keys.ip_not_allowed`	Die Anfrage kommt von einer Adresse außerhalb der erlaubten Adressen des Schlüssels.	Rufen Sie die API aus einem erlaubten Netz auf oder ändern Sie die Adressen des Schlüssels.
`403` `api_keys.mcp_only`	Ein persönlicher MCP-Schlüssel wurde außerhalb des Endpunkts `/mcp` verwendet.	Verwenden Sie für die API einen API-Schlüssel der Organisation.
`403` `oauth.operation_not_allowed`	Die Operation gehört nicht zur öffentlichen API, daher kann ein OAuth-Token sie nicht aufrufen.	Verwenden Sie eine Operation aus der API-Referenz.
`403` `org.suspended`	Die Organisation ist gesperrt. Die Daten der Organisation bleiben erhalten.	Wenden Sie sich an die Administration der Organisation.

403 bedeutet, dass die Anfrage authentifiziert, aber nicht erlaubt ist. Ein Objekt, das der Schlüssel nicht sehen darf, ergibt 404 – genau wie ein Objekt, das nicht existiert. So kann ein Schlüssel nicht herausfinden, was außerhalb seines Zugriffs liegt.

Im Namen eines Datenprofils handeln

Ein Schlüssel mit der Rolle admin kann prüfen, was eine andere Personengruppe sehen würde: Der Header X-View-As führt eine Anfrage im Namen eines Datenprofils und optional einer Rolle aus.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Anfragen in diesem Modus lesen nur: Jede Änderung ergibt 403 mit dem Code view_as.read_only. Ein OAuth-Token oder ein Schlüssel ohne die Rolle admin kann X-View-As nicht verwenden: Die Anfrage ergibt 403 mit dem Code view_as.admin_key_required. Ein Header, der kein vorhandenes Profil nennt, ergibt 400 mit dem Code view_as.invalid_header.

Browseranwendungen

Die API erlaubt Anfragen von jedem Web-Ursprung (Access-Control-Allow-Origin: *) und verwendet nie Cookies, sodass eine Seite sie mit fetch aufrufen kann. Der Schlüssel steckt dann in der Seite und ist für alle sichtbar, die sie verwenden. Rufen Sie die API aus dem Browser nur mit einem Schlüssel auf, den Sie diesen Personen zeigen können, etwa einem viewer-Schlüssel, der auf öffentliche Sammlungen beschränkt ist, oder schalten Sie Ihren eigenen Server zwischen Browser und Sursa.

Was nur Mitarbeitende tun können

Ein API-Schlüssel der Organisation handelt für die Organisation, nicht für eine Person. Zwei Teile der API gehören Personen, deshalb funktionieren sie nur mit einem Token, das im Namen einer mitarbeitenden Person handelt: einer Sitzung in Sursa oder einem OAuth-Zugriffstoken, das mit Zustimmung dieser Person ausgestellt wurde.

Unterhaltungen gehören einer Person. Ein API-Schlüssel der Organisation sieht in GET /v1/conversations nur die Unterhaltungen, die er selbst begonnen hat. Die öffentliche API hat keine Operation, die eine Unterhaltung beginnt, daher ist die Liste für einen Schlüssel normalerweise leer, und die Unterhaltungen von Mitarbeitenden werden ihm nie angezeigt. Fragen ohne Unterhaltung mit POST /v1/ask oder POST /v1/chat funktionieren mit jedem Schlüssel, der den Scope ask hat. Um die Unterhaltungen einer mitarbeitenden Person aufzulisten und den Verlauf einer davon mit GET /v1/conversations/{conv_id} zu lesen, rufen Sie die API mit einem OAuth-Token im Namen dieser Person auf. Das Token sieht nur die eigenen Unterhaltungen dieser Person; jede andere Unterhaltung ergibt 404 mit dem Code conversations.not_found.

Nur Mitarbeitende prüfen eine Karte. Die Prüfung bestätigt, dass eine Person den Inhalt kontrolliert hat. Daher brauchen POST /v1/cards/{card_id}/verification/verify und POST /v1/cards/{card_id}/verify eine Sitzung oder ein OAuth-Token im Namen einer mitarbeitenden Person, die die Karte prüfen darf. Mit einem API-Schlüssel der Organisation oder einem client_credentials-Token ergeben sie 400 mit dem Code cards.verify_user_account_required. Zuerst gelten die üblichen Regeln: Eine Karte, die der Schlüssel nicht sehen kann, ergibt 404, und ein Schlüssel, der sie nicht prüfen darf, ergibt 403.