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.

Steuern, was offengelegt wird

Die API-Offenlegung wird pro Objekt im Artefakt gesteuert, nicht am Gateway:

Setzen Sie apiEnabled: false auf einem Objekt, um es vollständig von der REST-Oberfläche fernzuhalten (seine Routen liefern 404).
Setzen Sie eine apiMethods-Whitelist (z. B. ['get', 'list']), um ein Objekt schreibgeschützt zu machen oder anderweitig einzuschränken, welche Operationen erreichbar sind.

Beide werden auf der REST-Ebene durchgesetzt — siehe REST-API → API-Oberfläche einschränken.

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.

API-Zugriff

On this page