Wenn du samarbeid mit Drittsystemen oder Automatisierungstools (wie IFTTT, Make, oder Zapier) verbinden möchtest, dann kannst du die samarbeid API benutzen. Damit kannst du beispielsweise aus den Drittsystemen Prozesse starten oder Dossiers erstellen. (Hier ein praktisches Beispiel.) Auch der samarbeid Skill – mit dem KI-Agenten in samarbeid mitarbeiten können – basiert auf der API. Um die API zu nutzen, benötigst du einen API-Schlüssel.
⚠️ HINWEIS: Die API wird aktiv weiterentwickelt. Unser Entwicklungsansatz ist, dass alle zukünftigen Änderungen abwärtskompatibel sind. Das bedeutet: Lösungen, die heute mit der API funktionieren, werden auch mit einer zukünftigen Version der API funktionieren.
Inhalt
API-Schlüssel erstellen
Um samarbeid per API aus Drittsystemen heraus zu nutzen oder deinen KI-Agenten mit dem samarbeid Skill mitarbeiten zu lassen benötigst du einen API-Schlüssel. (In manchen Drittsystemen wir der API-Schlüssel auch API-Token genannt. Damit ist das selbe gemeint.) Ein API-Schlüssel ist ein persönlicher Zugang für Drittsysteme. Mit ihm kannst du festlegen, welche Aktionen ein Drittsystem in deinem samarbeid ausführen darf. Du soltest ihn genauso wie ein Passwort schützen.
API-Schlüssel in samarbeid sind an die einzelnen Nutzer-Accounts geknüpft. Wenn ein Drittsystem über die API beispielsweise einen neuen Prozess mit deinem Schlüssel startet, dann wird im zugehörigen Event (in der Historie und im Journal) zu lesen sein, dass du den Prozess via API gestartet hast.
Um deinen API-Schlüssel zu erstellen gehe in den Bereich Einstellungen deines Nutzerprofils …
.. und wähle im Menü der linken Sidebar den Bereich API aus.
Du kannst für deinen Account mehrere API-Schlüssel erstellen und diesen unterschiedliche Rechte und Laufzeiten geben. So kannst du sicherstellen, dass bestimmte Drittsysteme nur bestimmte Aktionen in deinem samarbeid unter deinem Nahmen ausführen können.
Über den Button NEUER API-SCHLÜSSEL kannst du einen neuen API-Schlüssel erstellen.
Dabei musst du dem API-Schlüssel einen eindeutigen Namen geben. Dieser wird auch später in allen Events angezeigt, wenn eine Aktion per API über diesen Schlüssel ausgeführt wird. Zusätzlich kannst du dem Schlüssel noch einen Beschreibung geben. Zudem empfehlen wir, allen Schlüsseln ein Ablaufdatum zu geben. So stellst du sicher, dass der Zugang irgendwann deaktiviert wird, auch wenn du vergessen hast, deine API-Schlüssel zu managen.
Du kannst die Rechte für jeden einzelnen Schlüssel managen. Gib jedem Schlüssel maximal nur soviele Rechte, wie das Drittsystem, dass diesen API-Schlüssel nutzen wird, benötigt. Du kannst dem API-Schlüssel allgemein nur Leserechte oder Lese- und Schreibrechte geben. Alternativ kannst du feingranular Rechte vergeben, beispielsweise, dass über ein API-Schlüssel ausschließlich das Lesen und Erstellen von Kommentaren erlaubt ist.
Wenn du auf API-SCHLÜSSEL ERSTELLEN klickst wird dir in einem modalen Dialog der API-Token angezeigt, bzw. kannst du ihn in die Zwischenablage speichern. Es ist wichtig, dass du ihn dir in diesem Momement speicherst. Es ist nicht möglich, sich ihn später noch einmal anzuschauen.
Wichtig: Alle API-Schlüssel sind private Zugänge zu eurem samarbeid und sind Schlüssel für deinen samarbeid Account. Gib den Schlüssel also nur an Dritte weiter, wenn du dir absolut sicher bist. Behandle deine API-Schlüssel wie Passwörter. Teile ihn nur mit dem Drittsystem, das ihn benötigt. Wenn du vermutest, dass ein Schlüssel bekannt geworden ist, widerrufe ihn sofort und erstelle einen neuen. ↑ Top
API-Schlüssel nutzen
Die Abbildung zur feingranlularen Rechtevergabe veranschaulicht, welche Funktionen derzeit per API ausgeführt werden können. Mit der API können alle Daten in samarbeid gelesen werden und auf Instanzebene Daten geschrieben werden. Was derzeit nicht geht: das Erstellen und Bearbeiten von Prozess- und Dossiervorlagen, sowie das Hinzufügen, Bearbeiten und Löschen von Datenfeldern in laufenden Prozesse und Dossiers. Das Ändern der Daten in Datenfeldern ist hingegen überall möglich.
Du kannst für einen einmal erstellten Schlüssen den Namen, die Beschreibung, die Laufzeit der Gültigkeit sowie die Rechte verwalten. Klicke dazu auf BEARBEITEN in der Kachel des Schlüssel. Du kannst jedoch nicht den Schlüssel noch einmal sehen. Sollte der Schlüssel verloren gegangen sein, dann musst du einen neuen Schlüssel erstellen.
Wir haben für dich eine technische Dokumentation der samarbeid API (für diesen Link musst du in das Demosystem eingeloggt sein) erstellt. In deinem samarbeid findest du den Link zur aktuellen Dokumentation über die Kachel API-Dokumentation.
In der Dokumentation siehst du, welche Aktionen aktuell über die samarbeid-API ausgeführt werden können und wie diese konfiguriert werden müssen. ↑ Top
API-Schlüssel widerrufen
Du kannst jeden API-Token jederzeit widerrufen. Ab diesem Moment ist er deaktiviert und kein externes Drittsystem kann mit diesem Schlüssel mehr eine Aktion über die API in deinem Namen ausführen.
Sobald du einen API-Token widerrufen hast, kann kein System mehr über diesen Schlüssel auf dein samarbei zugreifen. ↑ Top
Samarbeid wird kontinuierlich weiterentwickelt. Da kann es passieren, dass Hilfetexte ungenau werden. Bitte schreibe uns eine Mail, wenn du Fragen oder Anregungen zu diesem Hilfetext hast: kontakt@samarbeid.org
Neugierig geworden – aber noch nicht sicher, ob samarbeid zu euch passt?
Ihr könnt jederzeit einen Demo-Termin buchen, in dem Fine euch samarbeid live vorstellt und ihr alle eure Fragen loswerden könnt. Der 30-Minuten-Termin ist unverbindlich, natürlich kostenfrei und kinderleicht zu buchen. ⬇️
Vielen Dank an Douglas Lopes für das Beitragsbild.