Dokumentation der API

Schlüssel und Zugangsverwaltung

Der Zugang zur API wird je Arbeitsbereich von Stonewake im Rahmen Ihrer Vereinbarung freigeschaltet. Danach verwalten die Administratorinnen und Administratoren des Arbeitsbereichs die Schlüssel selbst. Um den Zugang für Ihren Arbeitsbereich zu vereinbaren, wenden Sie sich an Ihre Ansprechperson bei Stonewake oder schreiben Sie an contact@stonewake.ai.

Im Dashboard

Eine Administratorin oder ein Administrator des Arbeitsbereichs kann die Schlüssel des Arbeitsbereichs im Dashboard unter den Einstellungen des Arbeitsbereichs anlegen, einsehen und widerrufen, oder über die API (nächster Abschnitt). Der vollständige Schlüssel wird einmal angezeigt, bei der Erstellung. Sichtbar bleiben danach der Name jedes Schlüssels, sein Anzeigepräfix (die ersten Zeichen des Schlüssels, um einen vorliegenden Schlüssel der Liste zuzuordnen) und seine Nutzungsdaten.

Über die API

Dieselben Vorgänge gibt es als Endpunkte unter /org/api-keys. Das sind Verwaltungsendpunkte. Sie authentifizieren sich mit den Anmeldedaten einer Administratorin oder eines Administrators des Arbeitsbereichs, also mit derselben Identität wie das Dashboard, nicht mit einem Schlüssel für die API. Schlüssel für die API funktionieren ausschließlich unter /v1 und über MCP; ein hierher gesendeter Schlüssel wird mit 401 abgelehnt und kann keine Schlüssel verwalten.

Einen Schlüssel anlegen

POST /org/api-keys

{
  "name": "reporting-pipeline",
  "expires_at": "2027-01-01T00:00:00Z",
  "team_id": "9d09b3e5e187"
}

name ist erforderlich, 1 bis 120 Zeichen. expires_at ist optional; ist es gesetzt, muss es eine Zeitzone tragen und in der Zukunft liegen, sonst wird die Anfrage mit 422 abgelehnt. Ohne Ablaufdatum bleibt der Schlüssel gültig, bis er widerrufen wird; im Dashboard angelegte Schlüssel tragen kein Ablaufdatum. team_id ist optional und nennt das eine Team Ihres Arbeitsbereichs, das der Schlüssel liest, so wie das Schlüsselformular im Dashboard die Teams anbietet; ohne Angabe liest der Schlüssel das Standardteam. Eine ID des Teams, die kein Team Ihres Arbeitsbereichs ist, wird mit 422 abgelehnt. Wie der Teamumfang wirkt, steht unter Aufrufer und Teamumfang. Bei Erfolg lautet die Antwort 201.

{
  "secret": "swk_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key": {
    "id": "6e9c8a2f-6d1c-4a0b-9d5e-3f2a1b0c9d8e",
    "name": "reporting-pipeline",
    "key_prefix": "swk_live_EXA",
    "role": "viewer",
    "scopes": ["read"],
    "team_id": "9d09b3e5e187",
    "team_name": "Export Finance",
    "created_by": "admin@example.com",
    "created_at": "2026-08-13T09:30:00Z",
    "last_used_at": null,
    "expires_at": "2027-01-01T00:00:00Z",
    "revoked_at": null
  }
}

secret ist der vollständige Schlüssel und erscheint ausschließlich in dieser Antwort. Speichern Sie ihn sofort; abrufbar ist er danach nicht mehr.

audit_export ist optional. Mit true erhält der Schlüssel zusätzlich den Umfang audit und darf das Prüfprotokoll Ihres Arbeitsbereichs unter GET /v1/audit-log.csv und über das Werkzeug für MCP audit_log_export lesen (siehe den Abschnitt Prüfprotokoll der Referenz der API). Für alles andere bleibt er ein lesender Schlüssel seines Teams. Im Dashboard bietet das Schlüsselformular dieselbe Wahl. Vergeben Sie den Prüfumfang nur an das System, das Ihre Prüfspur sammelt, etwa Ihr SIEM.

report_downloads ist optional. Mit true erhält der Schlüssel zusätzlich den Umfang reports und darf die Dokumente als PDF der Berichte und Ausschusspakete zu dem herunterladen, was er liest (siehe Referenz der API), zum Beispiel in eine Bibliothek in SharePoint (siehe SharePoint). Für alles andere bleibt er ein lesender Schlüssel seines Teams. Im Dashboard bietet das Schlüsselformular dieselbe Wahl als Darf auch Berichte und Pakete als PDF herunterladen.

Ist der Zugang zur API für den Arbeitsbereich nicht freigeschaltet, wird die Erstellung mit 403 abgelehnt.

{
  "detail": "API access is not enabled for your workspace. Contact your Stonewake representative."
}

Ein Schlüssel liest das Team, für das er ausgestellt wurde, solange dieses Team besteht. Wird das Team gelöscht, liest der Schlüssel nichts mehr und wird nie auf ein anderes Team umgelenkt. Jede Anfrage mit ihm an /v1 und jeder Werkzeugaufruf über MCP mit ihm, der Daten des Arbeitsbereichs liest, wird mit 403 und dem Fehlercode forbidden abgelehnt (siehe Fehler und Anfragebegrenzungen).

Die Schlüsselliste zeigt diesen Schlüssel dann mit team_name gleich null. Widerrufen Sie ihn und erstellen Sie einen neuen Schlüssel für eines der bestehenden Teams.

Schlüssel auflisten

GET /org/api-keys antwortet mit 200 und liefert die Schlüssel des Arbeitsbereichs, neueste zuerst, sowie den Status des Zugangs zur API des Arbeitsbereichs.

{
  "api_access_active": true,
  "api_access_expires_at": "2026-11-13T00:00:00Z",
  "keys": [
    {
      "id": "6e9c8a2f-6d1c-4a0b-9d5e-3f2a1b0c9d8e",
      "name": "reporting-pipeline",
      "key_prefix": "swk_live_EXA",
      "role": "viewer",
      "scopes": ["read"],
      "team_id": "9d09b3e5e187",
      "team_name": "Export Finance",
      "created_by": "admin@example.com",
      "created_at": "2026-08-13T09:30:00Z",
      "last_used_at": "2026-08-13T11:02:41Z",
      "expires_at": "2027-01-01T00:00:00Z",
      "revoked_at": null
    }
  ]
}

Widerrufene Schlüssel bleiben in der Liste. Schlüssel werden nie gelöscht, die Liste ist also eine vollständige Historie. api_access_expires_at ist nur gesetzt, solange der Zugang aktiv ist und ein Enddatum trägt; sonst ist der Wert null. Das Auflisten funktioniert auch, wenn der Zugang zur API des Arbeitsbereichs ausgelaufen ist, damit Sie Ihre Schlüssel jederzeit sehen.

Einen Schlüssel widerrufen

POST /org/api-keys/{key_id}/revoke antwortet mit 200 und den Metadaten des Schlüssels, wobei revoked_at nun gesetzt ist.

• Der Widerruf wirkt sofort, und der Schlüssel wird ab seiner nächsten Anfrage abgelehnt.
• Der erneute Widerruf eines bereits widerrufenen Schlüssels ändert nichts; das ursprüngliche revoked_at bleibt erhalten.
• Auf eine unbekannte ID des Schlüssels antwortet die API mit 404 und { "detail": "API key not found." }. Eine ID des Schlüssels aus einem anderen Arbeitsbereich erhält dieselbe 404; außerhalb Ihres Arbeitsbereichs bestätigt die API die Existenz von Ressourcen nicht.
• Der Widerruf funktioniert unabhängig vom Status des Zugangs zur API des Arbeitsbereichs. Einen Schlüssel können Sie jederzeit widerrufen.

Felder des Schlüsselobjekts