Scopes

Übersicht

Jeder Endpoint der i-Planner-API verlangt einen Scope nach dem Muster v3:<resource>:<action>. Der Token muss diesen Scope freigeschaltet haben, sonst antwortet die API mit HTTP 403 missing_required_scope.

Kern-Konvention: Der Scope hängt an den Daten, nicht am URL-Pfad. Beispiele:

• /v3/contracts/<id> und /v3/customers/<kid>/contracts brauchen beide v3:contracts:* — nicht v3:customers:*, weil Verträge eine eigene Daten-Domäne sind
• /v3/damages/<id> und /v3/customers/<kid>/damages brauchen v3:damages:* — analog Schäden
• /v3/customers/<kid>/addresses braucht v3:customers:* — Adressen sind direkte Felder am Customer-Datensatz, keine eigene Domäne
• /v3/portals/<id> und /v3/products/<kid>/portals brauchen v3:products:* — Portale teilen sich den Produkt-Scope
• /v3/customers/<kid>/relations braucht v3:customers:* — Beziehungen sind ein Cross-Reference-Layer am Customer

Eigenständige Daten-Domänen haben eigene Scope-Familien; "direkte" Customer-Sub-Resources teilen sich den Customer-Scope.

Scope-Anatomie

v3:<resource>:<action>
│  │          │
│  │          └── Action: `read` oder `write`
│  └────────────── Resource-Familie (siehe Liste unten)
└───────────────── API-Version (v3 = einzige öffentliche)

Actions: read für Lesen und write für Änderungen. Die Suche besitzt ausschließlich v3:search:read, der Posteingang ausschließlich v3:inbox:write. * ist hier eine Kurzschreibweise für die verfügbaren Actions und kein gültiger Scope-Wert. Schreiben schaltet Lesen nicht automatisch frei.

Für die Datenressourcen gilt:

Scope-Familien

Wo Scope-Familien geteilt sind

Mehrere Ressourcen teilen sich eine Scope-Familie:

Sub-Resource-Scope-Modelle

i-Planner kennt zwei Modelle, wie Sub-Resources auf Scopes abgebildet werden:

Unified Customer-Scope (direkte Sub-Resources)

Direkte Felder am Customer-Datensatz teilen sich den Customer-Scope:

• /v3/customers/<kid>/addresses → v3:customers:*
• /v3/customers/<kid>/banking → v3:customers:*
• /v3/customers/<kid>/contacts → v3:customers:*
• /v3/customers/<kid>/numbers → v3:customers:*
• /v3/customers/<kid>/identity → v3:customers:*
• /v3/customers/<kid>/jobs → v3:customers:*
• /v3/customers/<kid>/tags → v3:customers:*
• /v3/customers/<kid>/comments → v3:customers:*
• /v3/customers/<kid>/followers → v3:customers:*
• /v3/customers/<kid>/relations → v3:customers:*
• /v3/customers/<kid>/links → v3:customers:*
• /v3/products/<kid>/links → v3:products:* (Cross-Reference-Layer am Produktpartner)
• /v3/users/<kid>/links → v3:users:* (Cross-Reference-Layer am Benutzer)

Vorteil: Einfache Token-Konfiguration für Tools, die nur am Customer-Stamm arbeiten — ein einziger Scope reicht.

Eigenständige Daten-Domänen mit globally-unique id

Diese Sub-Domains haben eigene Scope-Familien — v3:customers:* reicht nicht — und liefern Full-CRUD top-level über die jeweilige id:

• /v3/contracts/<id> (CRUD) + /v3/customers/<kid>/contracts (List + Create) → v3:contracts:*
• /v3/damages/<id> (CRUD) + /v3/customers/<kid>/damages (List + Create) → v3:damages:*
• /v3/finances/<id> (CRUD) + /v3/customers/<kid>/finances (List + Create) → v3:finances:*
• /v3/goals/<id> (CRUD) + /v3/customers/<kid>/goals (List + Create) → v3:goals:*
• /v3/documents/<id> (CRUD) + /v3/customers/<kid>/documents (List + Create) → v3:documents:*
• /v3/activities/<id> (CRUD) + /v3/{customers|products|users}/<kid>/activities (List + Create) + /v3/activities/<id>/{comments|followers|tags} (Annotations) → v3:activities:*
• /v3/contact-persons/<id> (CRUD) + /v3/products/<kid>/contact-persons (List + Create) → v3:products:*
• /v3/portals/<id> (CRUD) + /v3/products/<kid>/portals (List + Create) → v3:products:*

Direkte Subs von Produktpartnern und Benutzern

Die direkten Stammdaten, Kommentare, Tags, Followers und Links eines Produktpartners verwenden v3:products:read|write; entsprechende Benutzer-Subs verwenden v3:users:read|write.

Dokumente und Aktivitäten behalten ihre eigenen Berechtigungen, auch unter /v3/products/{kid}/documents, /v3/users/{kid}/documents bzw. den jeweiligen /activities-Pfaden. Ein Produkt- oder Benutzer-Scope reicht dafür nicht.

Spezialfall: Such-API

Die Such-API↗ ist die einzige mit einem Zwei-Layer-Scope-Modell:

1. Endpoint-Layer: v3:search:read — ohne diesen Scope schlägt der Call sofort mit 403 fehl, unabhängig vom Inhalt
2. Per-Index-Layer: Pro Index, den die Query abfragt, wird zusätzlich der Read-Scope der entsprechenden Ressource geprüft

Fehlt ein Per-Index-Scope, kommt 403 forbidden_indices mit den verweigerten Indices in den Fehlerdetails. tariffs und commissions sind keine unterstützten Suchindices. portals ist als Index zulässig, liefert derzeit aber keine eigenen Suchtreffer.

Gespeicherte Token-Berechtigungen

Berechtigungen werden in den Einstellungen der Organisation verwaltet und bei jedem API-Aufruf neu geprüft. Die folgende Liste ist ein Beispiel freigeschalteter Scopes, kein JWT-Payload und kein Request-Body:

v3:customers:read
v3:customers:write
v3:contracts:read
v3:damages:read

Ein nicht freigeschalteter Scope ist gesperrt. Entfernst du einen Datenbereich oder deaktivierst eine Action im Editor, gilt dies ab dem nächsten Aufruf mit demselben Token-String. Eine leere Liste erteilt keinen Datenzugriff. Berechtigungen über den Plusbutton verwalten↗.

Beispiel-Token-Setups

Typische Integrationen und ihre minimalen Scope-Anforderungen:

Marketing-Integration

Geburtstags-Mails verschicken, Newsletter-Tag am Customer setzen.

v3:customers:read    ✓   (Name, Anrede, Geburtsdatum, E-Mail aus contacts[])
v3:customers:write   ✓   (Newsletter-Tag schreiben)

Mehr braucht's nicht. Verträge, Schäden, Finanzen, Ziele, Dokumente bleiben unsichtbar — Datenschutz-by-Design.

Provisions-Report

Org-weite Vertrags-Auswertung, monatlicher Excel-Export.

v3:contracts:read    ✓   (Verträge org-weit)
v3:damages:read      ✓   (Schadensquoten — eigene Scope-Familie)
v3:products:read     ✓   (Produktpartner-Stammdaten zur Vertragsauswertung)
v3:search:read       ✓   (Optional: Volltext über Verträge)

Full CRUD Backend-Sync

Bidirektionaler Daten-Sync zwischen i-Planner und einem externen CRM.

v3:customers:*       ✓   (Stammdaten + alle direkten Sub-Resources)
v3:contracts:*       ✓   (Verträge lesen + schreiben)
v3:damages:*         ✓   (Schäden lesen + schreiben)
v3:finances:*        ✓   (Finanzen lesen + schreiben)
v3:goals:*           ✓   (Ziele lesen + schreiben)
v3:documents:*       ✓   (PDFs hin und her — eigene Familie)
v3:activities:*      ✓   (Aktivitäten als Audit-Trail)

User-Management-Tool

Externes Tool zur Pflege von i-Planner-Benutzerstammdaten. Die REST-API schaltet keine Verwaltungsfunktionen für Organisationsrollen oder Lizenzen frei.

v3:users:*           ✓   (User-Stammdaten + alle Sub-Resources)
v3:system:read       ✓   (Optional: Sparten, Beziehungstypen und Tag-Katalog)

Verwandte Pages

• Authentifizierung↗ — Token-Erzeugung, JWT-Verwendung, Rotation
• Fehler↗ — 401/403-Bodies, Retry-Strategien
• Jede Resource-Page hat eine eigene Scopes-Sektion mit endpoint-genauer Auflistung (z. B. Customers > Scopes↗, Verträge > Scopes↗)