Quiply REST API

Quiply bietet eine REST API basierend auf SCIM 2 und OpenAPI zum Verwalten von Nutzern und Beiträgen an.

Um die API nutzen zu können, ist eine Freischaltung erforderlich. Nach der Freischaltung kann im Administrationsbereich unter API-Zugriff ein Passwort vergeben werden. Der Nutzername für den API-Zugriff ist vorgegeben und kann nicht geändert werden. Notieren Sie sich bitte das Passwort, bevor Sie speichern, denn es wird danach nicht wieder angezeigt.

Die API kann dann mit Basic-Authentication genutzt werden. Alternativ kann auch ein Bearer-Token angegeben werden, welches den gleichen Wert wie die Basic-Authentication hat.

Beispiel-Werte für den Authorization-Header mit Basic-Authentication bzw. Bearer-Token:

• Authorization: Basic d2lraTpwZWRpYQ==
• Authorization: Bearer d2lraTpwZWRpYQ==

Dieser Beitrag gibt nur einen kurzen Überblick. Die vollständige technische Dokumentation ist unter https://gateway.quiply.io/swagger-ui.html zu finden.

Umfang der Quiply REST API

Folgendes ist aktuell mit der Quiply REST API möglich:

• Nutzer (User) können erstellt, gelesen, aktualisiert, gelöscht und eingeladen werden.
• Nutzergruppen (Groups) können erstellt, gelesen, aktualisiert und gelöscht werden.
• Kanäle (Channels) können gelesen werden.
• Beiträge (Posts) können erstellt, gelesen, aktualisiert und gelöscht werden.
• Beitrag-Teaser-Bilder können hochgeladen und gelöscht werden.
• Beitragsanhänge konnen hochgeladen, gelesen und gelöscht werden.

Status der Quiply REST API

Die Quiply REST API befindet sich in der Beta-Phase und verwendet semantische Versionierung. Die aktuelle Major-Version ist 0, und spiegelt damit wider, dass sich die Quiply REST API in Entwicklung befindet.

Konkret bedeutet dies, dass neue (Minor-)Versionen nicht abwärtskompatible Änderungen mitbringen könnten. Generell versuchen wir aber, trotz Beta-Phase und Entwicklung die Quiply REST API möglichst stabil zu halten.

Insbesondere bei den SCIM 2-Endpunkten ("/scim/v2/"-Präfix) ist zu erwarten, dass die Funktionalität nur erweitert (etwa durch bessere Filter-Möglichkeiten) aber nicht geändert wird, da der SCIM 2-Standard hier technische Details größtenteils vorgibt.

⚠️ Die Quiply REST API steht derzeit mit eingeschränktem Support zur Verfügung. Um die Stabilität und Sicherheit der Plattform zu gewährleisten, kann es in Einzelfällen erforderlich sein, die Nutzung der API temporär einzuschränken.

Microsoft Entra ID (vormals Azure Active Directory, Azure AD) als SCIM-Provisioner

Microsoft Entra ID kann als SCIM-Provisioner eingerichtet werden, so dass Nutzerdaten vom Microsft Entra ID in die Quiply App übertragen werden könnnen. An dieser Stelle kann nur das initiale Einrichten erklärt werden. Microsoft bietet umfangreiche Dokumentation zum SCIM-Support in Microsoft Entra ID an.

Zum Einrichten gehen Sie wie folgt vor.

1. Erstellen Sie eine neue Enterprise Application und wählen Sie dabei "Create own application" statt eine Auswahl in der Microsoft Entra Gallery zu treffen.
   
2. Geben Sie im rechten Dialog einen Namen ein, bspw. "Quiply App" und wählen Sie die Option "Integrate any other application you don't find in the gallery (Non-gallery)". Bestätigen Sie mit "Create".
   
3. In der neu erstellen Enterprise Application navigieren Sie im linken Menü "Provisioning" und Klicken dann auf "Get started".
   
   
4. Wählen Sie den Provisioning Mode "Automatic" (1), geben Sie als Tenant URL "https://gateway.quiply.io/scim/v2/" ein (2) und geben Sie als Secret Token den Wert des Bearer-Tokens ein (3). Das Bearer-Token ergibt sich aus dem Muster `<Username>:<Passwort>` in Base64 codiert. Nach einem erfolgreichen Test mit "Test Connection" speichern Sie die Konfiguration mit "Save".
   
5. Zurück in Provisioning klicken Sie auf "Edit provisioning" und öffnen den Bereich "Mappings". Deaktivieren Sie die Option "Provision Microsoft Entra ID Groups" und für "Provision Microsoft Entra ID Users" entfernen Sie bitte alle Mappings bis auf die unten im Screenshot angezeigten. Hinweis: Sie müssen sie anderen Mappings nicht unbedingt entfernen, da nicht unterstütze Mappings von der Quiply REST API übernommen und immer unverändert zurück gegeben werden.
   
6. Aktivieren Sie schließlich das Provisioning und speichern Sie.
   
7. Standardmäßig werden nur Nutzer synchronisiert, die der gerade erstellten Enterprise Application zugewiesen sind. Nutzer können unter dem Menüpunkt "Users and groups" (1) mit "Add user/group" (2) hinzugefügt werden.