Sync- und Fachdienste an App-Berechtigungen anbinden

Nutzen Sie diesen Integrationsvertrag, wenn ein separater Sync-Service oder Fachdienst dieselben App-Rechte wie die Plattform durchsetzen muss. Nach der Einrichtung kann der Dienst Rechte online prüfen, lokal synchronisieren oder einen kurzlebigen signierten Grant validieren. Payment-, Identity- und Provider-Rohdaten verlassen den Server dabei nicht.

Integrationsart wählen

Variante	Geeignet für	Verhalten
Nativer Resolver	Modul im selben Workspace-Prozess	Direkter, tenantisolierter Domänenaufruf
Introspection	Einzelne Online-Entscheidung	Aktueller Zustand eines App-Akteurs
Snapshot plus Change-Feed	Eigene lokale Projektion	Vollständiger Startstand, danach sequenzielle Änderungen
Ed25519-Grant	Kurze Offline-Entscheidung	Audience-gebundener, kurzlebiger signierter Nachweis
Webhook	Schnelle Benachrichtigung	Mindestens einmal zugestellt; Feed bleibt Reconciliation-Vertrag

Für einen eigenständig deployten Sync-Service ist Snapshot plus Change-Feed der Standard. Webhooks verkürzen die Reaktionszeit, ersetzen aber keine Reconciliation.

Service-Bindung und Credential

Ein Administrator legt eine tenant- und appgebundene Service-Bindung mit Audience und erlaubten Fähigkeiten an. Rotieren Sie anschließend das Credential. Der Server zeigt dessen Secret nur bei der Ausgabe.

Senden Sie bei jedem authentisierten Request:

X-Nucleus-App-Service-Credential: ausgegebene Credential-ID und Secret gemäß Ausgabeformat,
X-Nucleus-App-Service-Timestamp: Unix-Zeit in Sekunden,
X-Nucleus-App-Service-Nonce: pro Request neuer kryptografischer Zufallswert,
X-Nucleus-App-Service-Signature: Signatur über den kanonischen Requestvertrag.

Die Signatur bindet HTTP-Methode, vollständigen Request-Pfad einschließlich Query, Zeitstempel, Nonce und SHA-256-Hash der tatsächlich gesendeten Body-Bytes. Ein signierter Request-Body darf höchstens 128 KiB groß sein. Verwenden Sie für jeden Versuch eine neue Nonce. Veraltete Zeitstempel, falsche Signaturen und wiederholte Nonces schlagen fehl.

Während des aktuellen Majors bleibt der vollständige bisherige Satz aus X-Workspace-Service-Credential, X-Workspace-Service-Timestamp, X-Workspace-Service-Nonce und X-Workspace-Service-Signature kompatibel. Senden Sie entweder den vollständigen kanonischen oder den vollständigen bisherigen Satz. Gemischte und unvollständige Sätze werden abgewiesen. Neue Integrationen verwenden ausschließlich die kanonischen Header.

Endpunkte verwenden

Methode und Pfad	Zweck
`GET /api/v1/public/v1/app-entitlements/service/introspect/{actorId}`	Einzelnen App-Akteur prüfen
`GET /api/v1/public/v1/app-entitlements/service/snapshot`	Seitenweisen Startstand laden
`GET /api/v1/public/v1/app-entitlements/service/changes?afterSequence=...`	Änderungen in Reihenfolge nachladen
`POST /api/v1/public/v1/app-entitlements/service/grants/{actorId}`	Kurzlebigen Grant ausstellen
`GET /api/v1/public/v1/app-entitlements/jwks`	Öffentliche Ed25519-Verifikationsschlüssel laden

Speichern Sie asOfSequence aus der ersten Snapshot-Seite. Senden Sie bei jeder Folgeseite sowohl cursor als auch dieselbe asOfSequence. Laden Sie danach Änderungen strikt aufsteigend ab dieser Sequenz. Antwortet der Feed mit ERR_APP_ENTITLEMENT_CURSOR_EXPIRED, verwerfen Sie die lokale Projektion und beginnen Sie mit einem neuen Snapshot.

Grants prüfen

Laden und cachen Sie die JWKS. Prüfen Sie Signatur, Schlüssel-ID, Issuer, Audience, nbf und exp. Als Ablaufgrenze verwendet exp bereits den früheren Zeitpunkt aus der Grant-TTL der Service-Bindung und der bekannten Gültigkeit der effektiven Berechtigung. Verwenden Sie valid_until nur als Information und niemals als Ersatz für die Prüfung von exp.

Ein gültiger Token allein gewährt noch keinen Zugriff. Prüfen Sie zusätzlich im verifizierten Token den Zustand sowie die konkret benötigten Features und Limits. Akzeptieren Sie keinen abgelaufenen Grant und verwenden Sie ihn nicht für eine andere Service-Bindung.

Webhooks sicher verarbeiten

Bestätigen Sie eine Lieferung erst nach dauerhafter Verarbeitung. Verwenden Sie Ereignis-ID und Sequenz zur Deduplizierung. Lieferungen können wiederholt oder verzögert eintreffen. Bei einer Lücke laden Sie den Change-Feed nach.

Der Server akzeptiert nur abgesicherte HTTPS-Ziele und blockiert private, Loopback- und anderweitig nicht zulässige Ziele. Legen Sie keine Credentials in die Ziel-URL. Während des Kompatibilitätsfensters enthalten Webhooks sowohl X-Nucleus-App-Service-Key als auch X-Workspace-Service-Key mit demselben Wert. Neue Empfänger verwenden den kanonischen Header und weisen eine Zustellung ab, wenn beide Werte voneinander abweichen.

Ergebnis prüfen

Testen Sie mindestens:

gültige Introspection und Snapshot/Feed-Fortsetzung,
falsche Audience, abgelaufenen Grant und eine Berechtigung, die vor der Grant-TTL endet,
Nonce-Replay und veralteten Zeitstempel,
eine doppelte Webhook-Lieferung,
einen abgelaufenen Feed-Cursor mit anschließendem Snapshot.

Der Dienst darf aus einer Benachrichtigung oder einem Store-Payload niemals selbst Rechte ableiten. Der Server bleibt die Entitlement-Autorität.