API-Tokens
Wie du ein Programm über die Base-URL an die REST-API anbindest, einen Zugangsschlüssel dafür anlegst, seine Rechte und seine Laufzeit festlegst, ihn regenerierst, deaktivierst und über den Schalter „Aktiv“ wieder einschaltest und wer dazu E-Mails bekommt.
Ein API-Token ist ein Schlüssel, mit dem ein anderes Programm auf deine i-Planner-Daten zugreifen darf, ohne Benutzername und Passwort. Du legst genau fest, welche Datenbereiche das Programm lesen und schreiben darf, welche Laufzeit der Schlüssel hat und von welchen Adressen aus er benutzt werden darf.
Kurz erklärt
Ein anderes Programm meldet sich mit einem Token an der REST-API an. Seine Aufrufe schickt es an die Base-URL https://www.api.i-planner.app. Den vollständigen Token zeigt i-Planner genau einmal, beim Anlegen oder Regenerieren. Danach siehst du nur noch einen Ausschnitt. Was der Token darf, entscheidet allein der Bereich Berechtigungen. Dazu kommen eine Laufzeit und auf Wunsch eine Liste erlaubter IP-Adressen. Die Seite Organisation › Einstellungen › Entwickler › API zeigt alle Tokens deiner Organisation in einer Tabelle.
Typische Aufgaben unter Organisation › Einstellungen › Entwickler › API:
- Ein Programm soll Daten aus i-Planner holen oder hineinschreiben: Token anlegen.
- Das Programm fragt nach der Adresse der Schnittstelle: Ein Programm mit der REST-API verbinden.
- Das Programm soll nur bestimmte Daten lesen dürfen: Berechtigungen festlegen.
- Der Token läuft bald ab: Gültigkeit.
- Der Schlüssel ist verloren gegangen: Token regenerieren.
- Ein Programm soll vorübergehend keinen Zugriff mehr haben: Token deaktivieren und wieder aktivieren.
- Der Assistant oder eine KI-App soll die Tokens auflisten oder einen widerrufen: API-Tokens über den Assistant oder MCP.
Voraussetzungen
- Deine Benutzerrolle braucht Zugriff auf die Einstellungen und in deren Detail-Rechten im Abschnitt Entwickler für das Auswahlfeld API mindestens Nur lesen. Fehlt der Zugriff, erscheint der Menüpunkt nicht. Mit Nur lesen steht in der Liste statt Bearbeiten der Eintrag Ansehen. Ein Token öffnet sich dann nur zum Ansehen. Alle Felder sind gesperrt, und die Zeile Token regenerieren fehlt.
- Zum Anlegen, Ändern, Kopieren, Aktivieren, Deaktivieren und Regenerieren brauchst du Lesen + Bearbeiten, zum Löschen Lesen + Bearbeiten + Löschen. Eine Person mit Administrator-Rolle vergibt das unter Benutzerrollen.
- Ein Programm auf der Gegenseite, in dem der Schlüssel hinterlegt wird.
- Euer Tarif begrenzt die Zahl der API-Schlüssel. Ein widerrufener Token, den du wieder aktivierst, zählt erneut mit.
Ein Programm mit der REST-API verbinden
Ein anderes Programm braucht zwei Angaben, um mit i-Planner zu arbeiten: die Adresse der REST-API und einen Token. Die Adresse ist die Base-URL https://www.api.i-planner.app. Sie ist für alle Organisationen dieselbe. Zu welcher Organisation ein Aufruf gehört, legt allein der Token fest.
- Trage im anderen Programm dort, wo es nach der Adresse der Schnittstelle fragt,
https://www.api.i-planner.appein. - Hinterlege dort außerdem den Token, den i-Planner beim Anlegen einmalig angezeigt hat. Wie du einen Token anlegst, steht unter Token anlegen. Ist er nicht mehr zur Hand, hilft Token regenerieren.
Auf der Seite Organisation › Einstellungen › Entwickler › API öffnet der Knopf Docs rechts über der Tabelle in einem neuen Tab die Anleitung zur REST-API in den Developer-Docs (https://www.api.i-planner.app/rest/v3/start). Dort steht die Base-URL ebenfalls, und dort steht, wie ein Aufruf aufgebaut ist. Hinter der Base-URL folgen /v3/ und der Datenbereich, etwa https://www.api.i-planner.app/v3/customers. Außerdem steht dort, dass das Programm den Token im Header Authorization: Bearer <Token> mitschickt.
Die Token-Übersicht
Unter Organisation › Einstellungen › Entwickler › API stehen alle API-Tokens deiner Organisation in einer Tabelle, die neuesten oben. Das sind nicht nur die, die du selbst angelegt hast. Mit dem Suchfeld Tokens filtern... grenzt du die Liste ein, oben rechts wechselst du zwischen Liste und Kacheln. Der Knopf Neuer Token legt einen neuen an. Solange noch kein Token angelegt ist, steht in der Tabelle Keine Tokens vorhanden.
| Spalte | Inhalt |
|---|---|
| Name | Der Name des Tokens |
| Token | Ein Ausschnitt aus Anfang und Ende des Tokens |
| Status | Aktiv (grün), Abgelaufen (orange), wenn die Laufzeit vorbei ist, oder Widerrufen (rot), wenn der Token gesperrt ist. Ein widerrufener Token funktioniert nicht, bis er wieder aktiviert wird. |
| Läuft ab | Das Ende der Laufzeit oder Unbegrenzt, wenn keine Laufzeit eingestellt ist |
| Zuletzt verwendet | Datum und Uhrzeit der letzten Nutzung. Wurde der Token noch nie benutzt, steht dort Noch nicht verwendet. |
| Erstellt am | Der Tag, an dem der Token angelegt wurde |
Die Beschreibung eines Tokens zeigt nur die Kachel-Ansicht. Jede Kachel nennt dazu den Namen, den Status, den Ausschnitt des Tokens und die letzte Nutzung.
Token anlegen
- Öffne Organisation › Einstellungen › Entwickler › API.
- Klicke rechts über der Liste auf Neuer Token. Die Seite Neuer Token öffnet sich.
- Trage unter Stammdaten ein:
- Name: Pflichtfeld. Er erscheint in der Übersicht und im Audit-Log. Lässt du ihn leer, meldet die Maske „Name darf nicht leer sein“.
- Beschreibung: optional. Unter der Beschriftung steht „Optional — wofür wird dieser Token eingesetzt?“ Die Beschreibung erscheint in der Kachel-Ansicht der Übersicht.
- Lege unter Berechtigungen fest, was der Token darf.
- Wähle unter Gültigkeit die Laufzeit. Voreingestellt sind 3 Monate.
- Trage unter IPs optional ein, von welchen Adressen aus der Token benutzt werden darf.
Wie überall im Bereich Organisation gibt es keinen Speichern-Knopf. Jede Änderung wird sofort gespeichert (siehe Speichern geschieht automatisch). Den Token selbst legt i-Planner aber erst an, sobald du das ausgefüllte Feld Name verlässt. Was du vorher an Berechtigungen und Laufzeit eingestellt hast, übernimmt i-Planner dabei mit. Danach erscheint unter Stammdaten auch der Schalter Aktiv.
Im selben Moment öffnet sich das Fenster Token erstellt. Darin steht der vollständige Token, zusammen mit dem roten Hinweis „Kopiere den Token jetzt. Nach dem Schließen wird er nicht mehr angezeigt.“ Klicke auf Token kopieren (danach steht dort Kopiert) und hinterlege den Token im anderen Programm. Schließe das Fenster erst dann mit Schließen. Welche Adresse das Programm dazu braucht, steht unter Ein Programm mit der REST-API verbinden.
Über Zurück zur Übersicht oben links kommst du wieder in die Liste.
Berechtigungen festlegen
Öffne den Token über Organisation › Einstellungen › Entwickler › API. Der Bereich Berechtigungen entscheidet, welche Daten der Token überhaupt anfassen darf. Nur was du hier ausdrücklich freigibst, ist erlaubt. Jeden anderen Aufruf lehnt die API mit Fehler 403 ab. Bei einem neuen Token ist die Liste leer, und dort steht „Noch keine Berechtigungen ausgewählt.“
- Klicke im Bereich Berechtigungen auf +.
- Wähle unter Datenbereich den Bereich aus, etwa Kunden. Ohne Auswahl meldet die Maske „Bitte einen Datenbereich auswählen.“
- Schalte Lesen und, falls nötig, Schreiben ein. Schreiben erlaubt das Anlegen, Ändern und Löschen in diesem Datenbereich.
Jede Zeile zeigt danach den Bereich und die erlaubten Aktionen, etwa Lesen · Schreiben, oder Keine Aktionen ausgewählt. Eine Zeile änderst du im Menü am rechten Rand mit Bearbeiten und entfernst sie mit Löschen.
| Datenbereich | Lesen | Schreiben |
|---|---|---|
| Kunden | ja | ja |
| Verträge | ja | ja |
| Schäden | ja | ja |
| Finanzen | ja | ja |
| Ziele | ja | ja |
| Aktivitäten | ja | ja |
| Dokumente | ja | ja |
| Posteingang | — | ja |
| Produkte | ja | ja |
| Suche | ja | — |
| Benutzer | ja | ja |
| System | ja | ja |
Gültigkeit
Öffne den Token über Organisation › Einstellungen › Entwickler › API. Unter Gültigkeit stellst du im Feld Gültig die Laufzeit des Tokens ein:
| Auswahl | Wirkung |
|---|---|
| 1 Monat | Laufzeit von einem Monat |
| 3 Monate | Laufzeit von drei Monaten, Voreinstellung bei einem neuen Token |
| 6 Monate | Laufzeit von sechs Monaten |
| Unbegrenzt (Lifetime) | Keine begrenzte Laufzeit |
Die Laufzeit zählt ab dem Zeitpunkt, an dem du sie auswählst. Nach einer Änderung steht darunter „Gültig bis <Datum>. Eine neue Laufzeit beginnt ab heute.“ Bei Unbegrenzt (Lifetime) steht dort „Dieser Token hat kein Ablaufdatum. Eine neue Laufzeit beginnt ab heute.“ Nach Ablauf lehnt die API jeden Aufruf mit diesem Token mit Fehler 401 ab. In der Liste unter Organisation › Einstellungen › Entwickler › API steht beim Token dann in der Spalte Status Abgelaufen. Gespeichert wird nur eine echte Änderung. Wählst du den Eintrag, der ohnehin schon dasteht, noch einmal aus, passiert nichts.
Links neben dem Auswahlfeld Gültig steht ein Warnzeichen. Fährst du mit der Maus darüber, erscheint der Hinweis „Unbegrenzte Tokens sind ein Sicherheitsrisiko. Wir empfehlen eine begrenzte Laufzeit.“
Zugriff auf bestimmte Adressen einschränken
Unter IPs legst du fest, von welchen Absender-Adressen Anfragen mit diesem Token überhaupt angenommen werden. Bleibt die Liste leer, gibt es keine Einschränkung. Sie zeigt dann „Noch keine IPs erfasst.“
- Öffne Organisation › Einstellungen › Entwickler › API und klicke auf die Zeile des Tokens oder wähle in ihrem Drei-Punkte-Menü den Eintrag Bearbeiten.
- Klicke im Bereich IPs auf +.
- Trage unter IP-Adresse eine einzelne IPv4-Adresse oder einen Adressbereich in CIDR-Schreibweise ein, zum Beispiel
203.0.113.5oder10.0.0.0/8.
Das Feld ist Pflicht. Eine leere Zeile musst du entweder ausfüllen oder wieder entfernen, sonst meldet die Maske „Bitte eine IP-Adresse eingeben.“ Passt das Format nicht, erscheint „Bitte eine gültige IPv4-Adresse oder CIDR-Notation eingeben, z. B. 10.0.0.0/8.“
Zum Ändern oder Entfernen einer Adresse wählst du im Menü am rechten Rand der Zeile Bearbeiten oder Löschen.
Token regenerieren
Brauchst du einen neuen Schlüssel, etwa weil der alte verloren ging, regenerierst du den Token.
- Öffne den Token über Organisation › Einstellungen › Entwickler › API.
- Im Bereich Token steht die Zeile Token regenerieren mit dem Ausschnitt des aktuellen Tokens unter Vorschau. Klicke dort auf Regenerieren.
- Das Fenster Token regeneriert zeigt den neuen Schlüssel einmalig. Kopiere ihn mit Token kopieren und schließe das Fenster mit Schließen.
Name, Beschreibung, Berechtigungen, Laufzeit und IP-Liste bleiben unverändert. Der bisherige Token verliert sofort seine Gültigkeit. Du musst ihn überall ersetzen, wo er hinterlegt ist. War der Eintrag deaktiviert, steht Aktiv danach wieder auf ein. Misslingt das Regenerieren, meldet i-Planner „Fehler beim Regenerieren“.
Bei einem noch nicht angelegten Token steht im Bereich Token „Wird erst nach dem Speichern des Tokens verfügbar.“ Ohne Bearbeitungsrecht fehlt die Zeile Token regenerieren ganz.
Token deaktivieren und wieder aktivieren
Mit dem Schalter Aktiv unter Stammdaten sperrst du einen Token vorübergehend, ohne ihn zu löschen. Die API lehnt einen deaktivierten Token ab, und in der Liste steht er in der Spalte Status auf Widerrufen.
- Zum Deaktivieren wählst du in der Liste im Drei-Punkte-Menü der Zeile Widerrufen oder schaltest Aktiv auf der Bearbeiten-Seite aus. Nach Widerrufen im Menü bestätigt i-Planner mit „Token widerrufen“.
- Zum Wiederaktivieren öffnest du den Token mit Bearbeiten und schaltest unter Stammdaten den Schalter Aktiv ein. Der Schlüssel bleibt derselbe und gilt innerhalb seiner Laufzeit sofort wieder. Im angebundenen Programm musst du nichts austauschen. Ist die Laufzeit schon vorbei, stelle unter Gültigkeit zusätzlich eine neue ein.
Bei einem bereits widerrufenen Token fehlt Widerrufen im Menü. Markierst du mehrere Tokens über ihre Kästchen, widerrufst du sie in einem Schritt. Klicke dafür unter der Tabelle auf Widerrufen und bestätige die Rückfrage. Bereits widerrufene Tokens bleiben unverändert. Ein wieder aktivierter Token zählt erneut gegen das Kontingent eures Tarifs für API-Schlüssel.
Token kopieren oder löschen
Öffne Organisation › Einstellungen › Entwickler › API und klicke am rechten Rand der Zeile auf das Drei-Punkte-Menü:
| Aktion | Wirkung |
|---|---|
| Bearbeiten | Öffnet den Token zum Ändern. Ohne Bearbeitungsrecht heißt der Eintrag Ansehen. |
| Kopieren | Legt einen zweiten Token mit dem Namen Kopie von … an und öffnet ihn direkt. Beschreibung, Berechtigungen, Ablaufdatum und IP-Liste werden übernommen. Der Schlüssel selbst wird neu erzeugt und einmalig angezeigt. Der kopierte Token bleibt unverändert gültig. |
| Widerrufen | Sperrt den Token, siehe Token deaktivieren und wieder aktivieren. Fehlt bei einem Token, der schon widerrufen ist. |
| Löschen | Entfernt den Eintrag endgültig. Die Rückfrage Token löschen? mit „Token ‚…‘ wirklich löschen? Er wird endgültig entfernt. Anwendungen, die ihn verwenden, verlieren sofort den Zugriff.“ bestätigst du mit Löschen. Danach meldet i-Planner „Token gelöscht“. |
Programme, die den bisherigen Token verwenden, haben ab sofort keinen Zugriff mehr, wenn du ihn deaktivierst, löschst oder regenerierst.
Weitere Empfänger benachrichtigen
Legt jemand einen Token an, kopiert, aktiviert, deaktiviert, regeneriert oder löscht ihn, schickt i-Planner eine E-Mail an diese Person und an alle Inhaber der Organisation. Läuft ein Token ab oder schlagen Aufrufe mit ihm fehl, geht die E-Mail an alle Inhaber. Im Bereich E-Mail-Benachrichtigung auf der Bearbeiten-Seite trägst du weitere Empfänger ein. Sie bekommen dieselben E-Mails zu diesem Token.
- Öffne den Token über Organisation › Einstellungen › Entwickler › API.
- Klicke im Bereich E-Mail-Benachrichtigung auf +.
- Trage unter E-Mail-Adresse die Adresse ein. Sie erhält technische Hinweise zusätzlich zum Inhaber.
Ist noch niemand eingetragen, steht dort „Der Inhaber wird bereits informiert. Noch keine weiteren Empfänger hinterlegt.“ Eine Zeile änderst du über Bearbeiten und löschst sie über Entfernen. Die Liste wird als Ganzes automatisch gespeichert. Doppelte Adressen fasst i-Planner zusammen und gleicht Groß- und Kleinschreibung an. Eine ungültige Adresse lehnt i-Planner mit „Bitte eine gültige E-Mail-Adresse eingeben.“ ab.
Die Mails tragen Titel wie „API-Token angelegt“, „API-Token kopiert“, „API-Token aktiviert“, „API-Token deaktiviert“, „API-Token erneuert“, „API-Token gelöscht“, „API-Token abgelaufen“ oder „API-Token: Aufrufe fehlgeschlagen“. Jede enthält den Knopf Token prüfen.
API-Tokens über den Assistant oder MCP
Der i-Planner-Assistant und eine über MCP verbundene KI-App wie Claude oder ChatGPT listen dir die Tokens deiner Organisation auf: mit Name, Beschreibung, Status (Aktiv, Abgelaufen oder Widerrufen), Laufzeit, letzter Nutzung, Berechtigungen und ob eine IP-Liste gilt. Den Token selbst und seinen Ausschnitt zeigen sie nie.
Einen Token widerrufen können sie auch. Das wirkt wie Widerrufen im Drei-Punkte-Menü auf dieser Seite: Programme mit diesem Token haben sofort keinen Zugriff mehr. Steht API-Schlüssel widerrufen unter Organisation › Einstellungen › KI & Agenten › Werkzeuge in der Spalte Assistant auf Mit Freigabe, speichert der Assistant das erst, wenn du die Freigabekarte mit Erlauben bestätigst. So ist es voreingestellt. Auf Aktiviert widerruft er ohne Karte. Über MCP führt i-Planner den Auftrag direkt aus. Ob die KI-App vorher nachfragt, entscheidet die App. Der Widerruf steht wie auf der Seite im Audit-Log und löst dieselbe E-Mail „API-Token deaktiviert“ aus, siehe Weitere Empfänger benachrichtigen.
Anlegen und Regenerieren gehen nie über die KI, denn den neuen Schlüssel zeigt i-Planner nur hier und nur einmal. Auch Wiederaktivieren, Berechtigungen, Gültigkeit, IP-Liste, E-Mail-Benachrichtigung, Kopieren und Löschen gehen nur hier auf der Seite.
Voraussetzungen:
- Unter Organisation › Einstellungen › KI & Agenten › Werkzeuge stehen die Werkzeuge API-Schlüssel lesen zum Auflisten und API-Schlüssel widerrufen zum Widerrufen nicht auf Deaktiviert, in der Spalte Assistant für den Assistant und in der Spalte MCP für MCP. Voreingestellt ist keines davon deaktiviert.
- Deine Rolle braucht für API dieselbe Stufe wie auf dieser Seite: Nur lesen zum Auflisten, Lesen + Bearbeiten zum Widerrufen. Einen eigenen Schalter für die Werkzeuge hat die Rolle nicht.
- Für MCP braucht deine Rolle MCP verwenden. Die verbundene KI-App arbeitet mit deinen Rechten, begrenzt durch die KI-Freigaben deiner Organisation, also durch die Spalte MCP unter Werkzeuge. Stellt deine Organisation dort ein Werkzeug später auf Aktiviert, kann die App es nutzen, sofern deine Rolle es erlaubt. Ein neu aktiviertes Werkzeug erscheint in der App, sobald sie ihre Werkzeugliste neu lädt, siehe Eine KI-App zeigt nicht alle Werkzeuge und MCP einrichten.
Häufige Fragen
Nein, einen neuen Token brauchst du dafür nicht. Öffne den bestehenden Token über Organisation › Einstellungen › Entwickler › API. Wähle unter Gültigkeit im Feld Gültig eine andere Laufzeit als die, die dort schon steht. Sie zählt ab dem Moment der Auswahl neu. Wählst du den bereits angezeigten Eintrag noch einmal, passiert nichts, denn gespeichert wird nur eine echte Änderung. Willst du wieder dieselbe Dauer, wähle kurz einen anderen Eintrag und dann den gewünschten. Der Schlüssel selbst bleibt unverändert, im angebundenen Programm musst du also nichts austauschen. Das geht auch bei einem bereits abgelaufenen Token. In der Spalte Status steht dann statt Abgelaufen wieder Aktiv. Ein widerrufener Token bleibt trotz neuer Laufzeit gesperrt, bis du unter Stammdaten den Schalter Aktiv einschaltest.
Deaktivieren, also Widerrufen im Drei-Punkte-Menü oder der Schalter Aktiv, ist der vorsichtige Weg. Der Eintrag bleibt mit dem Status Widerrufen in der Liste stehen, und du siehst weiterhin Name, Berechtigungen und wann er zuletzt benutzt wurde. Mit dem Schalter Aktiv unter Stammdaten nimmst du ihn später mit demselben Schlüssel wieder in Betrieb. Löschen entfernt den Eintrag endgültig. Diese Angaben sind dann weg, und für die angebundene Software legst du einen neuen Token an. In beiden Fällen endet der Zugriff sofort. Beides steht im Audit-Log, und beides wird per E-Mail gemeldet.
Nein, IPv6-Adressen werden nicht angenommen. Auf der Bearbeiten-Seite eines Tokens unter Organisation › Einstellungen › Entwickler › API nimmt der Bereich IPs nur IPv4-Adressen und Bereiche in CIDR-Schreibweise an, etwa 203.0.113.5 oder 10.0.0.0/8. Alles andere weist die Maske mit einer Fehlermeldung ab.
Weil mit einem Token ein neuer Zugang zu den Daten deiner Organisation entsteht. Beim Anlegen geht deshalb eine Nachricht mit dem Titel „API-Token angelegt“ an dich und an alle Inhaber der Organisation. Auch Kopieren, Aktivieren, Deaktivieren, Löschen und Regenerieren werden gemeldet, etwa mit „API-Token deaktiviert“, „API-Token gelöscht“ und „API-Token erneuert“. Solche Meldungen fasst i-Planner unter „API-Token geändert“ zusammen. Alle Adressen, die beim Token unter E-Mail-Benachrichtigung eingetragen sind, bekommen die Mails auch. So fällt auf, wenn jemand anders gehandelt hat.
i-Planner protokolliert jedes Anlegen, Ändern, Kopieren, Deaktivieren, Neu-Erzeugen und Löschen. Nachlesen kannst du es unter Organisation › Audit-Log im Protokoll Einstellungen.
Weitere Themen
- Fehlerbehebung: wenn das Programm die REST-API nicht erreicht, ein Aufruf mit 401 oder 403 abgelehnt wird oder der Token nicht mehr angezeigt wird.
- Webhooks: der umgekehrte Weg, bei dem i-Planner Änderungen an dein System meldet.
- Audit-Log: die eingehenden Aufrufe im Protokoll API und wer einen Token geändert hat.
- Audit-Log-Einstellungen: wie lange die API-Requests aufbewahrt werden.
- Benutzerrollen: wer Tokens ansehen, anlegen und löschen darf.