API-Dokumentation

Schlüssel und Zugangsverwaltung

Der API-Zugang 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 API-Schlüssel. API-Schlüssel haben ausschließlich Leserechte und können keine Schlüssel verwalten.

Einen Schlüssel anlegen

POST /org/api-keys

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

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. 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"],
    "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.

Ist der API-Zugang 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."
}

Schlüssel auflisten

GET /org/api-keys antwortet mit 200 und liefert die Schlüssel des Arbeitsbereichs, neueste zuerst, sowie den Status des API-Zugangs 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"],
      "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 API-Zugang 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: 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 Schlüssel-ID antwortet die API mit 404 und { "detail": "API key not found." }. Eine Schlüssel-ID 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 API-Zugangs des Arbeitsbereichs. Einen Schlüssel können Sie jederzeit widerrufen.

Felder des Schlüsselobjekts