Lizenzen und Berechtigungen

Ob ein Aufruf zugelassen wird, hängt an zwei voneinander unabhängigen Fragen:

1. Darf die Kanzlei die Schnittstelle überhaupt nutzen – und mit wem? Das ist die Lizenz.
2. Was darf der aufrufende Benutzer tun? Das sind die fachlichen Berechtigungen.

Fehlt das Erste, lautet die Antwort 403 LICENSE_MISSING. Fehlt das Zweite, 403 INSUFFICIENT_SCOPE.

⚠️ Maßgeblich ist Ihr Vertrag. Diese Seite beschreibt die Lizenzvarianten so, wie sie im Regelfall verkauft werden. Was Ihre Kanzlei tatsächlich nutzen darf, steht in Ihrer vertraglichen Vereinbarung mit STP – und die kann davon abweichen: im Umfang, in den Konditionen oder in einzelnen Bedingungen. Bei Abweichungen gilt der Vertrag, nicht diese Dokumentation. Im Zweifel fragen Sie Ihren Ansprechpartner bei STP.

Die beiden Lizenzvarianten

Eine Kanzlei kann auch beide besitzen. In dem Fall gilt die Volllizenz – sie ist die teurere und deckt den Aufruf ohnehin ab.

Der Unterschied in der Praxis

• Mit der Volllizenz kann die Kanzlei in ihrer eigenen Benutzerverwaltung Anwendungen registrieren. Eine Eigenentwicklung oder ein Automatisierungswerkzeug der Kanzlei bekommt damit einen eigenen Zugang, ohne dass STP etwas einrichten muss.
• Mit der partnergebundenen Lizenz funktioniert genau das nicht. Der Zugang ist an die Anmeldung des jeweiligen Partnerprodukts geknüpft. Versucht eine andere Anwendung den Zugriff, antwortet die Schnittstelle mit 403 CLIENT_NOT_LICENSED.

Was ein Aufruf braucht: immer zwei Berechtigungsbereiche

Jeder Aufruf wird gegen zwei Arten von Berechtigungsbereichen im Token geprüft:

Ein Lesezugriff braucht also zum Beispiel dms.cloud.api.standalone und dms.cloud.api.documents.read.

Welcher Capability-Scope für welchen Endpunkt gilt, steht in Endpunktübersicht.

Die Reihenfolge der Prüfung

Die Schnittstelle prüft in dieser Reihenfolge, und die erste nicht erfüllte Bedingung bestimmt die Antwort:

Die Schritte 1 bis 4 laufen in der Cloud und kosten keinen Weg in die Kanzlei. Schritt 5 findet im Dokumentenmanagement der Kanzlei statt.

Warum ein Token weniger Bereiche enthält als erwartet

Was tatsächlich im Token landet, ist die Schnittmenge aus drei Listen:

Bereiche im Token = was die Anwendung anfordern darf
                  ∩ was die Lizenz der Kanzlei hergibt
                  ∩ was die Rollen des Benutzers hergeben

Daraus folgen drei Beobachtungen, die im Alltag regelmäßig für Rückfragen sorgen:

• Ein Bereich, den die Anwendung nicht anfordern darf, kommt nie im Token an – ganz gleich wie gut die Kanzlei lizenziert ist.
• Eine Rolle ist nur ein Angebot. Die Rollen tragen beide Lizenzbereiche in sich; welcher davon wirklich im Token landet, entscheidet allein die Lizenz der Kanzlei.
• Eine Kanzlei mit Volllizenz erhält auch beim Aufruf über ein Partnerprodukt nur den Volllizenzbereich – und wird als Volllizenznutzer behandelt.

Die Rollen für das handelnde Konto

Vergeben werden sie über Gruppen; für jede Rolle liegt in jedem Mandanten eine Standardgruppe bereit. Einzelheiten und der Weg zu eigenen Gruppen stehen in Rollen und Gruppen.

Es gibt keine partnerspezifischen Rollen. Der Administrator der Kanzlei verwendet dieselben Rollen, unabhängig davon, welche Lizenz die Kanzlei besitzt – welcher Lizenzbereich daraus im Token landet, entscheidet allein die Lizenz.

Bei Fragen zum Umfang

Ob eine bestimmte Nutzung von Ihrer Lizenz gedeckt ist, lässt sich hier nicht abschließend beantworten – die Antwort steht in Ihrem Vertrag. Diese Seite hilft bei der technischen Einordnung: Sie erklärt, warum ein Aufruf abgelehnt wird und welche Stellschraube dahinter steckt. Ob die Stellschraube für Ihre Kanzlei anders gestellt werden darf, ist eine vertragliche Frage.

Weiterführend

• Erste Schritte
• Fehlercodes