Discovery und Ressourcen

Workspace-Integrationen sollen Fähigkeiten und Ressourcen zur Laufzeit entdecken. So bleiben Clients stabil, wenn ein Server zusätzliche Fähigkeiten veröffentlicht oder optionale Verträge nicht bereitstellt.

Nutzen Sie diese Seite, wenn Sie eigene Clients, Automatisierungen, B2B-Onlineshop-Integrationen oder Agenten gegen Workspace anbinden. Nach dem Lesen wissen Sie, welche öffentlichen Discovery-Endpunkte, Entry Points, Ressourcen-Metadaten und Readiness-Verträge Sie abfragen, bevor ein Client fachliche Daten liest oder verändert.

Öffentliche Discovery

Lesen Sie zuerst die öffentliche Discovery:

bash

nucli --host https://workspace.example discovery
nucli --host https://workspace.example discovery --json

GET/api/v1/meta/discovery

Die Antwort enthält API-Major, Build-Metadaten und öffentlich sichtbare Capabilities. Behandeln Sie Capabilities als fachlichen Vertrag. Versionen und Build-Zeitpunkte sind Diagnoseinformationen.

Der öffentliche Capability-Vertrag umfasst optionale Laufzeitfunktionen wie Headless-Login, Headless-Second-Factor, Headless-Bootstrap, Headless-Tenant-Wechsel, Headless-Handoff und OpenAPI-Privacy-Metadaten. Prüfen Sie die Capability, bevor Sie den zugehörigen Einstiegspunkt nutzen.

Öffentliche Einstiegspunkte

Headless-Clients lesen öffentliche Auth- und Onboarding-Einstiegspunkte über:

GET/api/v1/meta/entrypoints

bash

nucli --host https://workspace.example api --anonymous GET /api/v1/meta/entrypoints --summary

Nutzen Sie diese Antwort, bevor Sie Login-, 2FA- oder Tenant-Auswahl-Flows automatisieren.

Die Antwort listet pro Einstiegspunkt id, method, href und optional capability. Verwenden Sie href aus der Antwort und nicht lokal zusammengesetzte Auth-Pfade.

Typische Headless-Einstiegspunkte sind:

ID	Zweck
`auth.headless.login`	Startet einen Headless-Login.
`auth.headless.second_factor`	Schließt eine 2FA-Challenge ab.
`auth.headless.bootstrap.context`	Lädt den Bootstrap-Kontext für Headless-Clients.
`auth.headless.bootstrap.select_tenant`	Wählt einen Tenant für einen Bootstrap-Grant.
`auth.headless.switch_tenant`	Wechselt den aktiven Tenant einer Headless-Session.
`auth.headless.handoff.start`	Startet einen browserbestätigten Handoff.
`auth.headless.handoff.poll`	Pollt einen Handoff und erhält nach Freigabe eine Session.
`auth.headless.logout`	Beendet eine Headless-Session.

Authentifizierte Ressourcen

Nach dem Login lesen Clients tenantgebundene Ressourceneinstiege über:

GET/api/v1/profile/entrypoints

bash

nucli --tenant <tenant> resources list
nucli --tenant <tenant> resources meta <entrypoint-id>
nucli --tenant <tenant> resources get <entrypoint-id>

nucli resources verwendet anschließend nur noch die vom Server deklarierten Aktions-URLs und Methoden für get, create, update, patch und delete. Wenn ein Server diesen Vertrag nicht veröffentlicht, schlägt nucli resources geschlossen fehl. Verwenden Sie dann nucli api als expliziten Raw-Transport.

Lesen Sie resources meta <entrypoint-id>, bevor Sie Payloads bauen. Der Meta-Vertrag enthält den Primärschlüssel und die erlaubten Endpunkte. Für Create-, Update- und Patch-Aufrufe müssen Sie den Body explizit über --input übergeben; nucli ergänzt keine fachlichen Defaults.

Privacy-Metadaten

Nutzen Sie den Privacy-Katalog, wenn Sie API-Felder in Dokumentation, Exporten oder Fehlersuche-Artefakten bewerten:

bash

nucli --host https://workspace.example privacy
nucli privacy --file openapi.json --category contact.email
nucli privacy --file openapi.json --path /api/v1/contacts --json

GET/api/v1/meta/privacy

Der Server liefert nur Privacy-Metadaten aus OpenAPI-Annotationen. Er veröffentlicht darüber keine fachlichen Datensätze und nicht die vollständige OpenAPI-Spezifikation.

Privacy-Einträge enthalten je nach Annotation Pfad, Methode, Schema, Feld, JSON-Pointer, Klassifizierung, Kategorie, Redaction-, Log- und Export-Policy. Filtern Sie nach diesen Feldern, statt rohe OpenAPI-Spezifikationen in allgemein lesbaren Dateien abzulegen.

System-Readiness

Systemweite Readiness ist ein Vertrag des System-Mandanten:

bash

nucli --tenant system readiness list
nucli --tenant system readiness summary --json
nucli --tenant system readiness wait --domain <domain> --check <check> --timeout 30s

GET/api/v1/system/readiness

wait beendet Skripte mit stabilen Codes: 0 für ok, 1 für pending, warning oder Timeout, 2 für error und 3 für Request-, Auth-, Tenant-Guard- oder Vertragsfehler.

Integrationsregeln

Fragen Sie Capabilities ab, bevor Sie optionale Funktionen nutzen.
Speichern Sie keine rohen API-Antworten mit Personen- oder Kontaktdaten in allgemein lesbaren Dateien.
Prüfen Sie mit whoami oder scopes, bevor ein Skript Daten verändert.
Verwenden Sie für öffentliche tenantgebundene Endpunkte den jeweiligen Public-Vertrag wie Host, Pfad, Query-Parameter oder Public-Access-Token. --tenant-id wählt bei anonymen Requests keinen Tenant aus.