API + Sicherheit

0 Kurzkarte: Die API in 5 Schritten nutzen

Über die API (REST-Schnittstelle) lesen und ändern andere Systeme Daten im audatis MANAGER, z. B. ein SIEM, ein Ticketsystem oder ein eigenes Auswertungsskript. Der Zugriff läuft immer über ein persönliches API-Token und ist nur möglich, wenn alle Freigaben gesetzt sind.

1. System freischalten – Systemadministration: Systemeinstellungen → API + Sicherheit, Schalter API-Zugriff für Ihre Mandanten aktivieren einschalten, Speichern.
2. Mandant freischalten – auf derselben Seite in der Tabelle beim Mandanten Aktivieren wählen.
3. Rolle berechtigen – Mandantenadministration: in der Rolle der Person, Reiter Berechtigungen, Kategorie Einstellungen, Zeile API-Zugang auf Lesen, Schreiben oder Löschen setzen.
4. Token erstellen – die Person selbst: Mein Profil, Reiter API, + Neu. Bezeichnung, maximale Berechtigung und Mandanten wählen, Token sofort Kopieren.
5. Erste Anfrage senden – das Token im Kopf jeder Anfrage mitschicken: Authorization: Bearer am_… an https://<Ihre Adresse>/api/v1.

Wichtig: Das Token wird nur einmal angezeigt. Wer es weitergibt, gibt die eigenen Rechte weiter. Bewahren Sie es wie ein Passwort auf.

1 Einführung

1.1 Wofür ist die API da?

Die API macht die Daten des audatis MANAGER für andere Programme zugänglich. Typische Einsätze:

• Kontakte, Aufgaben oder Assets aus einem anderen System übernehmen oder abgleichen,
• Kennzahlen und Listen regelmäßig für eigene Auswertungen abrufen,
• Berichte automatisiert als Word- oder HTML-Datei erzeugen,
• Teilnehmende von Schulungen oder Nachweisen aus der Personalverwaltung einspielen.

Die API arbeitet mit genau den Rechten der Person, der das Token gehört. Sie sieht nichts, was diese Person in der Oberfläche nicht auch sehen dürfte, und sie kann nichts, was diese Person nicht auch dürfte.

1.2 Begriffe

1.3 Die Freigabekette

Ein Zugriff über die API gelingt nur, wenn jede Stufe ihn erlaubt. Es gilt immer die niedrigste Stufe.

Beispiel: Die Rolle hat API-Zugang: Löschen und im Modul Kontakte die Stufe Schreiben, das Token ist Nur lesen. Über die API kann die Person Kontakte nur abrufen – das Token ist die niedrigste Stufe.

1.4 Rollen und Rechte

2 API freischalten

Dieses Kapitel richtet sich an die Systemadministration.

Zugriff: Die Seite API + Sicherheit sehen nur Systemadministratoren. Sie steht unter Systemeinstellungen → API + Sicherheit. Ist die API serverseitig ausgeschaltet, fehlt der Menüpunkt.

Abbildung 1: Seite API + Sicherheit mit globalem Schalter und Mandanten-Tabelle

2.1 Die API für das System einschalten

1. Systemeinstellungen → API + Sicherheit öffnen.
2. Den Schalter API-Zugriff für Ihre Mandanten aktivieren einschalten.
3. In der Werkzeugleiste auf Speichern klicken.

Danach erscheint darunter die Tabelle der Mandanten. Der Schalter allein gibt noch keinen Mandanten frei.

Achtung: Schalten Sie den Schalter aus und speichern, ist die API für alle Mandanten des Systems sofort gesperrt. Dabei werden auch alle Mandanten-Freigaben auf Deaktiviert zurückgesetzt. Beim Wiedereinschalten müssen Sie die Mandanten erneut freigeben.

2.2 Einzelne Mandanten freigeben

Die Tabelle zeigt alle Mandanten des Systems, denen Sie zugewiesen sind.

So geben Sie einen Mandanten frei:

1. In der Zeile des Mandanten die Zeilenaktion Aktivieren wählen.
2. Die Änderung wird sofort gespeichert. Der API-Status wechselt auf Aktiviert.

Mit Deaktivieren sperren Sie den Mandanten wieder. Bereits erstellte Tokens behalten den Mandanten zwar in ihrer Liste, Zugriffe auf ihn werden aber abgelehnt. Im Profil der Token-Besitzer erscheint der Mandant dann als Berechtigung entzogen.

2.3 Mehrere Mandanten auf einmal

1. Die Kästchen vor den Mandanten anklicken.
2. In der Werkzeugleiste API aktivieren oder API deaktivieren wählen.

Über Suche in Tabelle und den Filter (Mandant, URL-Kennung, API-Status) grenzen Sie lange Listen ein. Der Filter bleibt für Sie gespeichert, bis Sie ihn zurücksetzen.

Tipp: Geben Sie die API nur für Mandanten frei, die sie tatsächlich brauchen. Jeder freigegebene Mandant ist eine zusätzliche Angriffsfläche.

2.4 Hinweis „Die API ist nicht betriebsbereit"

Erscheint oben auf der Seite ein gelber Hinweis zum API-Token-Pepper, ist die API auf dem Server noch nicht vollständig eingerichtet. Die API beantwortet dann jede Anfrage mit Fehler 403, unabhängig von Ihren Einstellungen. Diese Einstellung nimmt nur der Betreiber in der Serverkonfiguration vor – wenden Sie sich an den Support.

3 Rollen für die API berechtigen

Dieses Kapitel richtet sich an die Mandantenadministration.

Ob und wie weit eine Person die API nutzen darf, steuert die Berechtigung API-Zugang in ihrer Rolle.

1. Die Rolle öffnen und auf Bearbeiten gehen (siehe Handbuch Rollen).
2. Reiter Berechtigungen, Kategorie Einstellungen aufklappen.
3. In der Zeile API-Zugang eine Stufe wählen.
4. Speichern.

Abbildung 2: Berechtigung API-Zugang in der Kategorie Einstellungen

Die Stufe API-Zugang gibt keine Module frei. Was die Person in den einzelnen Modulen lesen oder ändern darf, bestimmen weiterhin die Modulzeilen der Rolle. Hat eine Person in mehreren Mandanten unterschiedliche Rollen, gilt in jedem Mandanten die dortige Rolle.

Hinweis: Die Zeile API-Zugang erscheint nur, wenn die API auf dem Server betriebsbereit ist.

4 API-Tokens verwalten

Dieses Kapitel richtet sich an alle Benutzer mit API-Zugang.

Den Reiter API finden Sie über das Personen-Symbol → Mein Profil. Er erscheint nur, wenn Ihre Rolle in mindestens einem Mandanten API-Zugang hat. Fehlt das Recht, zeigt der Reiter den Hinweis, dass Ihr Benutzer nicht für die API freigeschaltet ist.

Abbildung 3: Reiter API im Profil mit Nutzungsstatistik und Token-Tabelle

Oben sehen Sie Ihre persönliche Nutzung der letzten 30 Tage:

Über API-Dokumentation öffnen Sie die technische Beschreibung in einem neuen Fenster.

4.1 Ein Token erstellen

1. Im Reiter API in der Werkzeugleiste auf + Neu klicken.
2. Bezeichnung eingeben, z. B. „SIEM Export". Sie erkennen das Token später daran wieder.
3. Maximale Berechtigung dieses Tokens wählen: Nur lesen, Lesen und schreiben oder Lesen, schreiben und löschen.
4. Bei Mandanten mindestens einen Mandanten wählen. Zur Auswahl stehen nur Mandanten, die für die API freigegeben sind und in denen Ihre Rolle API-Zugang hat.
5. Optional ein Ablaufdatum setzen. Ohne Datum bleibt das Token unbegrenzt gültig.
6. Speichern.

Abbildung 4: Dialog Neues API-Token erstellen

Der Dialog API-Token erstellt zeigt das Token. Klicken Sie auf Kopieren und legen Sie es sofort in einem Passwort-Manager oder direkt in Ihrer Anbindung ab. Nach Verstanden lässt es sich nicht mehr anzeigen.

Abbildung 5: Dialog API-Token erstellt mit einmaliger Anzeige

Tipp: Wählen Sie die kleinste nötige Berechtigung. Für reine Auswertungen reicht Nur lesen. Setzen Sie für befristete Vorhaben ein Ablaufdatum, damit vergessene Tokens nicht dauerhaft gültig bleiben.

4.2 Die Token-Tabelle

4.3 Ein Token erneuern

Erneuern Sie ein Token regelmäßig, nach einem Personalwechsel oder wenn es in falsche Hände geraten sein könnte.

1. In der Zeile des Tokens die Aktion Token erneuern wählen.
2. Im Dialog Token erneuern bestätigen.
3. Das neue Token Kopieren und in allen angebundenen Systemen eintragen.

Das bisherige Token ist sofort ungültig. Abgelaufene Tokens lassen sich nicht erneuern – legen Sie dafür ein neues an.

4.4 Ein Token löschen

1. In der Zeile des Tokens Löschen wählen.
2. Im Dialog Token widerrufen bestätigen.

Das Token wird unwiderruflich gelöscht. Alle Systeme, die es verwenden, verlieren sofort den Zugriff.

5 Ein System anbinden

Dieses Kapitel richtet sich an Entwickler und Integratoren.

5.1 Die API-Dokumentation

Unter https://<Ihre Adresse>/api/ finden Sie die technische Dokumentation. Sie öffnet sich, wenn Sie im audatis MANAGER angemeldet sind oder ein gültiges Token mitschicken.

Abbildung 6: Startseite der API-Dokumentation

Die Dokumentation ist in Englisch. Sie ist die verbindliche Referenz für Felder und Werte; dieses Kapitel erklärt die Grundregeln.

5.2 Anmeldung

Jede Anfrage braucht das Token im Kopf:

` Authorization: Bearer am_… `

Erster Test:

` curl -H "Authorization: Bearer am_…" https://<Ihre Adresse>/api/v1 `

Die Antwort enthält Name und Version der API sowie Verweise auf die Mandantenliste, die Sprachen und die Dokumentation. GET /api/v1/clients zeigt die Mandanten, auf die Ihr Token zugreifen darf, mit ihrer Mandanten-ID (id), ihrer URL-Kennung (slug) und Verweisen auf alle Bereiche des Mandanten.

5.3 Aufbau der Adressen

Fast alle Daten gehören zu einem Mandanten. Die Adresse enthält deshalb die Mandanten-ID:

` /api/v1/clients/{mid}/contacts Liste /api/v1/clients/{mid}/contacts/{kid} ein Eintrag `

Auswahllisten, die für alle Mandanten gleich sind (z. B. Status oder Typen), stehen ohne Mandanten-ID, z. B. /api/v1/tasks/statuses.

Beim Anlegen und Ändern senden Sie JSON mit Content-Type: application/json.

5.4 Verfügbare Bereiche

5.5 Listen und Seiten

Listen werden seitenweise geliefert. Steuern Sie das mit ?page= (ab 1) und ?per_page= (Standard 25, höchstens 200; größere Werte werden auf 200 begrenzt). Jede Antwort enthält

• data – die Einträge,
• meta – total (Anzahl aller Einträge), page, per_page, total_pages,
• _links – Verweise auf self, first, last und, wenn vorhanden, prev und next.

Folgen Sie für weitere Seiten den Verweisen in _links, statt Adressen selbst zusammenzusetzen.

5.6 Datums- und Zeitangaben

Leere Datumsfelder liefert die API als null.

5.7 Fehlermeldungen

Fehler kommen immer als JSON:

` { "error": { "code": "VALIDATION_ERROR", "message": "Request body does not match schema", "details": [ "/: The required properties (last_name) are missing" ] } } `

details erscheint nur bei Validierungsfehlern und nennt je Zeile das betroffene Feld.

6 Sicherheit und Datenschutz

Für Systemadministration, Datenschutzbeauftragte und Informationssicherheit.

• Tokens sind persönlich. Jede Anfrage läuft unter dem Namen der Person, der das Token gehört, und wird so protokolliert. Legen Sie für Integrationen eine eigene, eng berechtigte Person an, statt das Token einer Administratorin zu verwenden.
• Kleinste Rechte. Kombinieren Sie eine passende Rolle mit der kleinsten Token-Berechtigung und nur den nötigen Mandanten.
• Befristen und erneuern. Setzen Sie Ablaufdaten und erneuern Sie Tokens regelmäßig. Löschen Sie Tokens, die nicht mehr gebraucht werden.
• Nur verschlüsselt. Rufen Sie die API immer über https:// auf und speichern Sie Tokens nie im Klartext in Skripten oder Repositorys.
• Sofort sperren. Bei Verdacht auf Missbrauch: Token löschen, bei Bedarf den Mandanten auf API + Sicherheit deaktivieren oder dort die API für das ganze System ausschalten.
• Auftragsverarbeitung prüfen. Wer Daten über die API an ein anderes System überträgt, gibt sie an einen weiteren Empfänger weiter. Prüfen Sie, ob dieses System im Verzeichnis der Verarbeitungstätigkeiten und – bei externen Anbietern – in der Auftragsverarbeitung erfasst ist.

7 Glossar

8 Häufige Fragen

Im Profil fehlt der Reiter API. Warum? Ihre Rolle hat in keinem Mandanten das Recht API-Zugang, oder die API ist auf dem Server nicht betriebsbereit. Wenden Sie sich an Ihre Mandantenadministration.

Beim Erstellen eines Tokens wird mein Mandant nicht angeboten. Der Mandant ist auf API + Sicherheit nicht freigegeben, oder Ihre Rolle hat dort keinen API-Zugang. Beides muss erfüllt sein.

Ich habe das Token nicht kopiert. Kann ich es noch einmal anzeigen? Nein. Wählen Sie Token erneuern oder legen Sie ein neues Token an. Das alte wird dabei ungültig bzw. bleibt ungenutzt und sollte gelöscht werden.

Meine Anfrage liefert 403, obwohl das Token gültig ist. Eine Stufe der Freigabekette fehlt: Token-Berechtigung zu niedrig (z. B. Nur lesen bei POST), Mandant nicht im Token, Rolle ohne passenden API-Zugang, Modulrecht zu niedrig oder Mandant nicht freigegeben. Bei API_DISABLED ist die API im System oder für den Mandanten ausgeschaltet.

Sieht die API mehr als ich in der Oberfläche? Nein. Das Token erbt Ihre Rechte und kann nie mehr, als Sie in dem jeweiligen Mandanten dürfen.

Was passiert mit meinen Tokens, wenn mein Konto gesperrt wird oder ich das Unternehmen verlasse? Löschen Sie Tokens vor dem Ausscheiden selbst. Angebundene Systeme sollten auf ein Token einer Person umgestellt werden, die die Integration weiter betreut.

Wird jeder Zugriff protokolliert? Ja. Ihre eigene Nutzung sehen Sie in der Statistik im Reiter API.