API-Dokumentation

Authentifizierung

Jede Anfrage an die Stonewake API führt einen API-Schlüssel als Bearer-Token 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.

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 Einweg-Hash 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.
  • 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 bei der Erstellung gesetztes Ablaufdatum tragen.

Das Verhalten bei 401

Eine /v1-Anfrage, 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 API-Zugang 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 API-Schlüssel wie Passwörter.

  • Setzen Sie einen Schlüssel niemals in eine URL oder einen 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 Secrets-Verwaltung 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.