Dokumentation der API

Authentifizierung

Jede Anfrage an die Stonewake API führt einen Schlüssel für die API als Token vom Typ Bearer im Header Authorization mit.

bash
curl https://api.stonewake.ai/v1/portfolio \
  -H "Authorization: Bearer swk_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Der Schlüssel oben ist ein Platzhalter. Echte Schlüssel bestehen aus dem Präfix swk_live_ gefolgt von 40 zufälligen Zeichen.

Das Schema Bearer wird in beliebiger Schreibweise gelesen, auch bearer und BEARER funktionieren. Ein Leerzeichen trennt es vom Schlüssel, und weitere Leerzeichen oder Tabulatoren vor dem Schlüssel sowie Leerzeichen oder Tabulatoren nach ihm werden ignoriert. Kein anderes Zeichen wird entfernt, daher macht jedes andere Zeichen vor, in oder nach dem Schlüssel ihn zu einem anderen Schlüssel, der wie ein falscher Schlüssel abgelehnt wird. Ein Tabulator anstelle dieses Leerzeichens, das Schema ohne Schlüssel oder ein anderes Schema sendet gar keinen Schlüssel. Der Server für MCP liest den Header genauso.

Wie Schlüssel funktionieren

  • Schlüssel werden von einer Administratorin oder einem Administrator des Arbeitsbereichs im Dashboard unter den Einstellungen des Arbeitsbereichs oder über die API angelegt. Siehe Schlüssel und Zugangsverwaltung.
  • Der vollständige Schlüssel wird genau einmal angezeigt, bei der Erstellung. Gespeichert wird er als Einweghash und lässt sich nicht erneut abrufen. Geht ein Schlüssel verloren, legen Sie einen neuen an.
  • Schlüssel gelten für Ihren Arbeitsbereich. Ein Schlüssel kann ausschließlich Daten lesen, die zu dem Arbeitsbereich gehören, in dem er angelegt wurde, und seine Bestände (Transaktionen, Portfolio, Screenings) sind die des einen Teams, für das er ausgestellt wurde. Siehe Aufrufer und Teamumfang.
  • Schlüssel funktionieren ausschließlich mit der REST API unter /v1 und über MCP. Jeder andere Endpunkt, auch die Endpunkte des Dashboards und der Schlüsselverwaltung, lehnt einen Schlüssel mit 401 ab, genau wie einen ungültigen Schlüssel.
  • Schlüssel haben ausschließlich Leserechte. Ein Schlüssel kann in Ihrem Arbeitsbereich nichts ändern, und er kann keine Schlüssel verwalten, auch sich selbst nicht.
  • Schlüssel lassen sich sofort widerrufen. Der Widerruf wirkt ab der nächsten Anfrage dieses Schlüssels.
  • Schlüssel können ein Ablaufdatum tragen, das beim Anlegen über die API gesetzt wird. Ein Schlüssel ohne Ablaufdatum, darunter jeder im Dashboard angelegte Schlüssel, bleibt gültig, bis er widerrufen wird.

Das Verhalten bei 401

Eine Anfrage an /v1, deren Zugangsdaten fehlen oder nicht akzeptiert werden, erhält stets dieselbe Antwort, unabhängig vom Grund.

json
{
  "error": {
    "code": "unauthenticated",
    "message": "Missing or invalid credentials."
  }
}

Ein fehlender Header, ein fehlerhaft aufgebauter Schlüssel, ein falscher Schlüssel, ein widerrufener Schlüssel, ein abgelaufener Schlüssel und ein Schlüssel aus einem Arbeitsbereich, dessen Zugang zur API ausgelaufen ist, sind in der Antwort nicht voneinander zu unterscheiden. Die API gibt nicht preis, warum Zugangsdaten abgelehnt wurden oder ob sie überhaupt jemals existiert haben. Erhält ein zuvor funktionierender Schlüssel plötzlich 401, prüfen Sie seinen Status im Dashboard.

Regeln im Umgang mit Schlüsseln

Behandeln Sie Schlüssel für die API wie Passwörter.

  • Setzen Sie einen Schlüssel niemals in eine URL oder eine Abfragezeichenfolge (Query String). Er gehört ausschließlich in den Header Authorization.
  • Liefern Sie einen Schlüssel niemals in clientseitigem Code oder in etwas aus, das ein Browser herunterlädt. Aufrufe gehören auf Ihre Serverseite.
  • Halten Sie Schlüssel aus der Versionsverwaltung und aus Protokollen heraus. Bewahren Sie sie in einer Verwaltung der Geheimnisse oder einer Umgebungsvariable auf.
  • Tauschen Sie den Schlüssel bei Verdacht aus. Könnte ein Schlüssel offengelegt worden sein, legen Sie einen Ersatz an und widerrufen Sie den alten Schlüssel sofort.