CLI und API

Entwickler nutzen Workspace-APIs, um eigene Anwendungen, Integrationen, Websites und Automationen zu bauen. nucli ist das passende Werkzeug, wenn Sie Schnittstellen erkunden und API-Aufrufe reproduzierbar testen wollen.

nucli spricht HTTP gegen eine laufende Workspace-Instanz. Es liest keine Serverkonfiguration, greift nicht direkt auf Datenbanken zu und nutzt für authentifizierte Aufrufe den angemeldeten Workspace-Kontext.

Einstieg

Beginnen Sie mit der Discovery-API. Sie zeigt die API-Major-Version, Build-Metadaten und öffentliche Capabilities einer Workspace-Instanz:

GET/api/v1/meta/discovery

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

Die JSON-Antwort ist ein Envelope. Lesen Sie data.apiMajor, data.serverVersion, data.builtAt und data.capabilities; meta enthält technische Antwortmetadaten. Nutzen Sie data.capabilities, um optionale Funktionen zu prüfen. Konkrete Einstiegspunkte lesen Sie separat über GET /api/v1/meta/entrypoints.

Wenn ein Endpunkt eine Anmeldung braucht, melden Sie sich zuerst an:

nucli --host https://workspace.example login --email <email>
nucli api GET /api/v1/profile/entrypoints --summary

Für Skripte lesen Sie das Passwort über stdin und wählen bei mehreren Mandanten den erwarteten Tenant explizit:

printf '%s\n' "$WORKSPACE_PASSWORD" \
  | nucli --host https://workspace.example --tenant <tenant> --tenant-id <tenant-id> \
      login --email <email> --password-stdin --otp "$WORKSPACE_OTP"

nucli login verwendet den Headless-Auth-Vertrag. Es speichert kein Passwort. Für kurzlebige CI- oder Automationsläufe kann ein Prozess-Token über die Umgebung bereitstehen; nucli persistiert diesen Wert nicht.

Für den Headless-Login prüft nucli zuerst die Capability auth.headless.login aus GET /api/v1/meta/discovery und nutzt danach den serververöffentlichten Entrypoint auth.headless.login aus GET /api/v1/meta/entrypoints.

Mit nucli profiles use <alias> setzen Sie einen lokalen Tenant-Alias als Standardprofil für nachfolgende Befehle ohne --tenant.

Ressourcen entdecken

Nutzen Sie Ressourcenlisten, bevor Sie konkrete IDs in Skripte übernehmen:

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

Für Änderungen nutzen Sie nur Aktionen, die der Server in resources meta veröffentlicht:

nucli --tenant <tenant> resources create <entrypoint-id> --input payload.json --summary
nucli --tenant <tenant> resources update <entrypoint-id> <id> --input payload.json --summary
nucli --tenant <tenant> resources patch <entrypoint-id> <id> --input patch.json --summary
nucli --tenant <tenant> resources delete <entrypoint-id> <id> --summary

resources get <entrypoint-id> --all --max-pages <n> sammelt paginierte Listen begrenzt ein. Für Einzelobjekte ist --all nicht erlaubt.

Für Nested-Ressourcen ersetzen Sie vom Server veröffentlichte Pfadparameter mit --param name=value. Beispiel:

nucli --tenant <tenant> resources create companies.employments --param companyId=<company-id> --input employment.json --summary
nucli --tenant <tenant> resources patch people <person-id> --input person-patch.json --summary

Kontext prüfen

Prüfen Sie vor mutierenden API-Aufrufen den ausgewählten Kontext:

nucli --tenant <tenant> whoami
nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> scopes

whoami zeigt Profil, Host, Tenant-Alias, aktive Tenant-ID und ob eine Session verfügbar ist. Es gibt keine Personendaten, Tokenwerte, Cookie-Werte oder Tokenquellen aus.

Nutzen Sie doctor, wenn Sie Host, Profil, Tokenstore, Session, Tenant-Guard und Discovery prüfen wollen:

nucli --tenant <tenant> doctor
nucli --tenant <tenant> doctor --json

diagnose liest tenantgebundene Diagnosewerte aus einem angemeldeten Kontext und gibt nur kuratierte Status- und Zählwerte aus:

nucli --tenant <tenant> diagnose --json
nucli diagnose --all-tenants --json

Schreibanfragen mit Sitzung absichern

Verwendet Ihr Client ein Session-Cookie, benötigen Schreibanfragen einen CSRF-Schutz gegen unbeabsichtigte Aktionen durch fremde Websites. Im Browser muss eine mitgesendete Origin zu Schema, Host und Port der Zieladresse passen. Ein vorhandener Sec-Fetch-Site-Header muss same-origin sein. Auch eine andere Subdomain gilt nicht als dieselbe Origin.

Native Clients ohne diese beiden Browser-Header senden stattdessen genau einen Header x-nucleus-csrf: 1. nucli setzt ihn bei Cookie-Schreibanfragen automatisch, auch bei Multipart- und Binärübertragungen. Aktualisieren Sie ältere Clients vor dem Serverwechsel. Der Marker ersetzt keine Anmeldung und kann widersprüchliche Browser-Header nicht überstimmen.

GET, HEAD und OPTIONS benötigen diesen Schutz normalerweise nicht. WebSocket-Upgrades, über die der Client persistente Änderungen übertragen kann, gelten jedoch als Schreibzugriff und werden ebenfalls geprüft. Maßgeblich ist die tatsächlich verwendete Authentifizierung: Ein autoritativer Bearer- oder Basic-Zugang bekommt durch ein zusätzliches Cookie keine Browserpflicht. Endpunkte, die ausdrücklich eine Browser-Sitzung verlangen, behalten ihre strengeren Anforderungen.

Senden Sie für JSON-CRUD-Anfragen Content-Type: application/json; MIME-Parameter wie charset=utf-8 sind zulässig. Authentifizierungsanfragen enthalten genau ein JSON-Objekt mit bekannten Feldern und höchstens 64 KiB. Payment-Webhooks dürfen höchstens 1 MiB enthalten. Für diese begrenzten Bodys gilt eine Lesefrist von 15 Sekunden.

Unvollständige oder zu große Bodys beenden bei HTTP/1 auch die Verbindung. Öffnen Sie für die nächste Anfrage eine neue Verbindung. Bei HTTP/2 bleiben andere Streams nutzbar. Kann der Server die Lesefrist nicht durchsetzen, weist er die Anfrage mit 503 ERR_REQUEST_READ ab.

Der Read-only-Deployment-Preflight unterstützt ausschließlich Sitzungen und Bearer-API-Schlüssel. Basic und andere Authentifizierungsmethoden erhalten 401 ERR_AUTH_METHOD_UNSUPPORTED, auch wenn zusätzlich ein Sitzungscookie vorliegt. Verwenden Sie einen unterstützten Zugang mit den erforderlichen Systemberechtigungen.

Prüfen Sie nach der Client-Umstellung eine erlaubte Schreibaktion. 403 ERR_BROWSER_ORIGIN weist auf fehlenden oder widersprüchlichen Browser-Kontext beziehungsweise den fehlenden nativen Marker hin. 415 bedeutet einen unzulässigen Medientyp, 413 ERR_REQUEST_TOO_LARGE einen zu großen Body. Wiederholen Sie solche Anfragen erst nach Korrektur.

API-Aufrufe protokollieren

Für reproduzierbare Fehlersuche speichern Sie Antworten in Dateien und reduzieren die Konsolenausgabe:

nucli api GET /api/v1/meta/privacy --summary --save privacy.json
nucli api GET /api/v1/meta/privacy --redact --save privacy-redacted.json

GET/api/v1/meta/privacy

--summary gibt nur Metadaten wie Methode, URL, Status, Content-Type, Größe und Request-ID aus. --redact maskiert bekannte sensible JSON-Felder und bricht bei Nicht-JSON-Antworten ab, ohne den Raw-Body auszugeben.

--save schreibt den Body mit eingeschränkten Dateirechten. Kombinieren Sie --save und --redact, wenn eine Antwort Personen-, Kontakt-, Token-, Adress-, IBAN- oder BIC-Felder enthalten kann. Query-Parameter mit sensiblen Namen werden in Summary-URLs maskiert.

Für paginierte GET-Listen kann nucli Seiten begrenzt einsammeln:

nucli --tenant <tenant> api GET /api/v1/import-jobs --all --max-pages 5 --summary

--all folgt meta.pagination.nextOffset, setzt ohne vorhandenen count- oder limit-Parameter count=100 und markiert das Ergebnis als truncated, wenn --max-pages erreicht ist.

Privacy-Felder prüfen

Nutzen Sie den Privacy-Katalog, bevor Sie Felder in Exporten oder Fehlersuche-Artefakten verwenden:

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

Der Serververtrag veröffentlicht nur Felder mit expliziter Privacy-Metadatenannotation. Ein leerer Treffer bedeutet nicht, dass eine fachliche Antwort frei von Personen- oder Geschäftsdaten ist.

Browser-Ansicht

Öffnen Sie einfache GET-Endpunkte im Browser, wenn Sie die Browser-Session prüfen wollen:

nucli --host https://workspace.example discovery --web
nucli api --web /api/v1/meta/discovery

--web führt keinen HTTP-Aufruf aus nucli heraus aus. Der Browser nutzt seine eigenen Cookies. Deshalb akzeptiert nucli api --web nur GET-Aufrufe ohne Body und ohne eigene Header.

Mehrere Implementierungen dokumentieren

Wenn Sie Anwendungsbeispiele schreiben, zeigen Sie die gleiche Aufgabe pro Sprache oder Werkzeug in Tabs:

curl -s https://workspace.example/api/v1/meta/discovery

nucli api GET /api/v1/meta/discovery --anonymous --summary