Skip to content

api-access.de.mdx

Latest commit

 

History

History
124 lines (95 loc) · 5.21 KB

api-access.de.mdx

File metadata and controls

124 lines (95 loc) · 5.21 KB
Raw
title API-Zugriff
description Generierte REST-APIs, Authentifizierung und API-Schlüssel für Integrationen.

API-Zugriff

Jedes im Artefakt deklarierte Objekt wird über eine generierte REST-API bereitgestellt. Dieselben Endpunkte versorgen die UI, Integrationen und Kunden-ETL-Skripte — es gibt keine separate „Integrations-API", die gepflegt werden müsste.

Basis-URL

https://<project-domain>/api/v1

Wichtige Schnittstellen:

Pfad Zweck
/api/v1/data/<object> Generiertes CRUD für jedes Objekt (z. B. /api/v1/data/account)
/api/v1/data/<object>/{id} Einzelnen Datensatz lesen/aktualisieren/löschen
/api/v1/actions/<object>/<action> Eine deklarative Aktion aufrufen (POST)
/api/v1/auth/* Authentifizierung (Anmeldung, Sitzungen, OAuth, OIDC)
/api/v1/meta/* Metadaten-APIs (Objekte, Felder, Ansichten), sofern aktiviert
/api/v1/keys Erzeugt einen nur einmal angezeigten sys_api_key für den aufrufenden Benutzer (POST)
/api/v1/mcp Model-Context-Protocol-Server über Streamable HTTP, wenn OS_MCP_SERVER_ENABLED=true
/api/v1/health Liveness-/Readiness-Probe (keine Authentifizierung)

Das Präfix lautet standardmäßig /api/v1 (der API-basePath von /api plus die version v1) und ist im ObjectOS-Stack konfigurierbar.

Authentifizierungsoptionen

Aufrufer können sich auf drei Arten authentifizieren:

Methode Am besten geeignet für Wie
Sitzungs-Cookie Browser-/UI-Verkehr Anmeldung über /api/v1/auth/*; Cookies sind auf den Projekt-Hostnamen beschränkt
Bearer-Zugriffstoken Mobile, SPA, kurzlebige Server-Jobs Anmeldedaten unter /api/v1/auth/sign-in/email austauschen und Authorization: Bearer <token> übergeben
API-Schlüssel Server-zu-Server, ETL, langlebige Integrationen Einen sys_api_key erstellen und als Bearer-Token übergeben

Alle drei durchlaufen dasselbe AuthPlugin und werden zu einem sys_user-Kontext aufgelöst, den das SecurityPlugin anhand von Berechtigungen und Datensatzzugriff auswertet.

API-Schlüssel

API-Schlüssel sind erstklassige sys_api_key-Datensätze. Der Schlüsselwert selbst wird gehasht gespeichert — nur das prefix und Metadaten bleiben abfragbar, sodass ein durchgesickerter Schlüssel nicht aus der Datenbank rekonstruiert werden kann.

Es gibt zwei Wege, einen Schlüssel auszustellen:

  • Console — melden Sie sich als Administrator bei Console → API Keys an, wählen Sie den besitzenden Benutzer, legen Sie optional ein Ablaufdatum fest und kopieren Sie das angezeigte Geheimnis einmalig.

  • Self-Service-Endpunkt — POST /api/v1/keys erzeugt einen Schlüssel für den authentifizierten Aufrufer und gibt das rohe Geheimnis genau einmal zurück. Der Schlüssel ist an den eigenen Benutzer des Aufrufers gebunden und kann daher nicht zur Identitätsübernahme verwendet werden:

    curl -X POST https://app.example.com/api/v1/keys \
  -H "Authorization: Bearer <session-or-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "etl-pipeline"}'
# → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" }

Übergeben Sie den Schlüssel bei nachfolgenden Anfragen als Bearer-Token, als x-api-key-Header oder als Authorization: ApiKey. Die REST-Daten- und Metadaten-APIs authentifizieren ihn über denselben Verifier wie MCP, unter den Berechtigungen und der Datensatz-Sicherheit des Schlüsselinhabers:

curl https://app.example.com/api/v1/data/account \
  -H "x-api-key: os_pk_live_…"

Um einen Schlüssel zu widerrufen, führen Sie die Aktion revoke_api_key für den entsprechenden sys_api_key-Datensatz aus (auch in der Console-UI verfügbar). Der Widerruf wird ab der nächsten Anfrage sofort wirksam.

Paginierung, Filterung und Sortierung

Generierte Listen-Endpunkte akzeptieren die standardmäßigen ObjectStack-Abfrageparameter:

Parameter Bedeutung
?limit= Seitengröße (unterliegt einer serverseitigen Obergrenze)
?offset= oder ?cursor= Paginierung
?filter= Serverseitige Filterung mit der ObjectQL-Filtersyntax
?sort= Sortierausdruck (z. B. -created_at)
?fields= Sparse-Feldauswahl

Die vollständige Filtergrammatik finden Sie in der Framework-Dokumentation — die Laufzeitgrammatik ist die maßgebliche Quelle.

Ratenbegrenzung

Verwenden Sie das RateLimiter-Primitiv des Frameworks (oder Ihr Ingress / API-Gateway), um Limits pro IP und pro Identität anzuwenden. Empfohlene Ausgangswerte sind unter Production readiness dokumentiert.

CORS

Wenn Aufrufer in einem Browser mit einem anderen Origin ausgeführt werden, konfigurieren Sie CORS am Ingress oder über die Middleware der Laufzeit. Kombinieren Sie Wildcard-Origins nicht mit Anfragen, die Anmeldedaten enthalten.

OpenAPI / Discovery

Die Laufzeit kann ein OpenAPI-Dokument für die generierte REST-API bereitstellen, wenn die entsprechende Funktion im Image enthalten ist. Kundenintegrationen sollten Clients aus dem OpenAPI-Dokument pro Deployment generieren, anstatt URLs von Hand zu erstellen, da Objektnamen und generierte Routen dem bereitgestellten Artefakt folgen.