API-Tokens

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 dabei 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.

Voraussetzungen

• Deine Benutzerrolle braucht Zugriff auf die Einstellungen und im Bereich Entwickler für die Seite API-Tokens mindestens Nur lesen. Fehlt der Zugriff, erscheint der Menüpunkt nicht. Mit Nur lesen steht in der Liste statt Bearbeiten der Eintrag Ansehen.
• 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.

Die Token-Übersicht

Unter Organisation › Einstellungen › Entwickler › API stehen alle API-Tokens deiner Organisation — nicht nur die, die du selbst angelegt hast. Die Zeile über der Liste zeigt, wie viele es sind; rechts daneben legt der +-Knopf einen neuen an, sein Hinweistext lautet Neuer Token.

Jede Zeile zeigt den Namen und darunter zwei Angaben: die Beschreibung des Tokens — oder, wenn keine hinterlegt ist, einen kurzen Ausschnitt des Tokens — sowie Zuletzt verwendet mit Datum und Uhrzeit. Wurde der Token noch nie benutzt, steht dort Noch nicht verwendet.

Der farbige Punkt links davor unterscheidet genau diese beiden Fälle:

Rechts steht ein Kennzeichen zum Zustand:

Token anlegen

1. Öffne Organisation › Einstellungen › Entwickler › API.
2. Klicke rechts in der Zeile über der Liste auf +. Die Seite Neuer Token öffnet sich.
3. 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. Wofür wird dieser Token eingesetzt? Sie ersetzt in der Übersicht den Token-Ausschnitt.
4. Lege unter Berechtigungen fest, was der Token darf.
5. Wähle unter Gültigkeit die Laufzeit. Voreingestellt sind 3 Monate.
6. 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 Organisation › Übersicht). Auf dieser Seite gilt eine Besonderheit: Angelegt wird der Token erst, sobald du das ausgefüllte Feld Name verlässt — was du vorher an Berechtigungen und Laufzeit eingestellt hast, wird dabei mit übernommen. 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), hinterlege den Token im anderen Programm und schließe das Fenster erst dann mit Schließen.

Ü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 — jeder andere Aufruf wird mit Fehler 403 abgelehnt. Bei einem neuen Token ist die Liste leer, dort steht Noch keine Berechtigungen ausgewählt.

1. Klicke im Bereich Berechtigungen auf +.
2. Wähle unter Datenbereich den Bereich aus, etwa Kunden. Ohne Auswahl meldet die Maske Bitte einen Datenbereich auswählen.
3. 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.

Gültigkeit

Öffne den Token über Organisation › Einstellungen › Entwickler › API. Unter Gültigkeit stellst du im Feld Gültig die Laufzeit des Tokens ein:

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) 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. Ist sie vorbei, steht beim Token in der Liste unter Organisation › Einstellungen › Entwickler › API das Kennzeichen Abgelaufen. Gespeichert wird nur eine echte Änderung: Wählst du den Eintrag, der ohnehin schon dasteht, noch einmal aus, passiert nichts.

Neben der Beschriftung 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 — sie zeigt dann Noch keine IPs erfasst. —, gibt es keine Einschränkung.

1. Öffne Organisation › Einstellungen › Entwickler › API und klicke auf die Zeile des Tokens — oder wähle in ihrem Drei-Punkte-Menü den Eintrag Bearbeiten.
2. Klicke im Bereich IPs auf +.
3. Trage unter IP-Adresse eine einzelne IPv4-Adresse oder einen Adressbereich in CIDR-Schreibweise ein, zum Beispiel 203.0.113.5 oder 10.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, kommt Bitte eine gültige IPv4-Adresse oder CIDR-Notation eingeben, z. B. 10.0.0.0/8.

Zum Ändern oder Entfernen einer Adresse nutzt du das 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.

1. Öffne den Token über Organisation › Einstellungen › Entwickler › API.
2. Im Bereich Token steht die Zeile Token regenerieren mit dem Ausschnitt des aktuellen Tokens unter Vorschau. Klicke dort auf Regenerieren.
3. 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 und muss überall ersetzt werden, 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 dort Wird erst nach dem Speichern des Tokens verfügbar. Ohne Bearbeitungsrecht ist Regenerieren gesperrt.

Token deaktivieren und wieder aktivieren

Mit dem Schalter Aktiv unter Stammdaten sperrst du einen Token vorübergehend, ohne ihn zu löschen. Ein deaktivierter Token wird von der API abgelehnt und steht in der Liste mit dem Kennzeichen Widerrufen.

• Deaktivieren: Wähle in der Liste im Drei-Punkte-Menü der Zeile Deaktivieren oder schalte Aktiv auf der Bearbeiten-Seite aus.
• Wieder aktivieren: Öffne den Token mit Bearbeiten und schalte 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.

Das Menü zeigt immer Deaktivieren, auch bei einem bereits widerrufenen Token; dann meldet i-Planner Token nicht gefunden oder bereits widerrufen. 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ü:

Deaktiviert, gelöscht oder regeneriert — in allen drei Fällen haben Programme, die den bisherigen Token verwenden, ab sofort keinen Zugriff mehr.

Weitere Empfänger benachrichtigen

Über wichtige Ereignisse eines Tokens informiert i-Planner per E-Mail immer den Inhaber. Im Bereich E-Mail-Benachrichtigung auf der Bearbeiten-Seite trägst du weitere Empfänger ein. Sie erhalten Hinweise bei Erstellung, Aktivierung, Deaktivierung, Regenerierung, Ablauf, REST-API-Limit und technischen Fehlern dieses Tokens.

1. Öffne den Token über Organisation › Einstellungen › Entwickler › API.
2. Klicke im Bereich E-Mail-Benachrichtigung auf +.
3. 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, Groß- und Kleinschreibung wird angeglichen. 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 und enthalten den Knopf Token prüfen.

Häufige Fragen

Warum sehe ich den Menüpunkt „API Tokens" nicht?

Deiner Benutzerrolle fehlt der Zugriff auf die Einstellungen oder im Bereich Entwickler auf die Seite API-Tokens (so heißt sie in der Benutzerrolle). Eine Person mit Administrator-Rolle gibt das unter Organisation › Einstellungen › Team & Rollen › Benutzerrollen frei — Nur lesen genügt zum Ansehen, Lesen + Bearbeiten zum Anlegen und Ändern.

Ich habe das Fenster mit dem Token weggeklickt — wo sehe ich ihn noch einmal?

Gar nicht. Der vollständige Token wird genau einmal angezeigt; danach zeigt i-Planner nur noch einen Ausschnitt aus Anfang und Ende, auf der Bearbeiten-Seite im Bereich Token unter Vorschau. Öffne den Token über Organisation › Einstellungen › Entwickler › API und klicke im Bereich Token auf Regenerieren — dann bekommst du im Fenster Token regeneriert einen neuen Schlüssel angezeigt. Der bisherige gilt ab diesem Moment nicht mehr und muss im angebundenen Programm ersetzt werden.

Mein Aufruf wird mit „403" abgelehnt.

Wird ein Aufruf mit Fehler 403 abgelehnt, prüfe den Token unter Organisation › Einstellungen › Entwickler › API auf zwei Punkte. Erstens die Berechtigungen: Nur ausdrücklich freigegebene Datenbereiche sind erlaubt. Lege also mit + eine Zeile für den passenden Datenbereich an oder schalte in der vorhandenen Zeile Lesen beziehungsweise Schreiben ein. Zweitens die IPs: Stehen dort Adressen, nimmt i-Planner Anfragen mit diesem Token nur von diesen Adressen an.

Mein Aufruf wird mit „401" abgelehnt.

Wird ein Aufruf mit Fehler 401 abgelehnt, erkennt i-Planner den Token selbst nicht (mehr) an. Prüfe die Liste unter Organisation › Einstellungen › Entwickler › API: Steht beim Token Widerrufen, wurde er deaktiviert — schalte ihn über Bearbeiten mit Aktiv wieder ein. Fehlt der Eintrag ganz, wurde er gelöscht. Andernfalls prüfe, ob der Token zwischenzeitlich über Regenerieren ersetzt wurde und im anderen Programm noch der alte Schlüssel liegt.

Mein Token läuft bald ab. Muss ich einen neuen anlegen?

Nein, einen neuen Token brauchst du dafür nicht. Öffne den bestehenden Token über Organisation › Einstellungen › Entwickler › API und 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. Auch bei einem bereits abgelaufenen Token geht das — das Kennzeichen Abgelaufen verschwindet dann wieder. Ein widerrufener Token bleibt trotz neuer Laufzeit gesperrt, bis du unter Stammdaten den Schalter Aktiv einschaltest.

Kann ich einen deaktivierten Token wieder in Betrieb nehmen?

Ja, mit demselben Schlüssel. Öffne den Token über Organisation › Einstellungen › Entwickler › API mit Bearbeiten und schalte unter Stammdaten den Schalter Aktiv ein. Der Token gilt innerhalb seiner Laufzeit sofort wieder; im angebundenen Programm musst du nichts ändern. Er zählt dann wieder gegen das Kontingent eures Tarifs für API-Schlüssel. Ist die Laufzeit schon vorbei, stelle unter Gültigkeit zusätzlich eine neue ein.

Ich will Daten nur abholen lassen, nichts verändern.

Öffne den Token über Organisation › Einstellungen › Entwickler › API und lege unter Berechtigungen nur Zeilen für die Datenbereiche an, die das Programm braucht. Schalte darin Lesen ein und lass Schreiben ausgeschaltet.

Der Punkt vor meinem Token ist rot — stimmt etwas nicht?

Nein. Ein roter Punkt vor einem API-Token heißt nur, dass dieser Token noch nie verwendet wurde; unter seinem Namen steht dann Noch nicht verwendet. Sobald der Token benutzt wurde, ist der Punkt grün und dort steht Zuletzt verwendet mit Datum und Uhrzeit.

Ich brauche einen zweiten Token mit denselben Rechten.

Öffne Organisation › Einstellungen › Entwickler › API und wähle im Drei-Punkte-Menü der Zeile den Eintrag Kopieren. Beschreibung, Berechtigungen, Ablaufdatum und IP-Liste werden übernommen, der neue Eintrag heißt Kopie von … und bekommt einen eigenen, frisch erzeugten Schlüssel, der einmalig angezeigt wird. Der kopierte Token bleibt gültig.

Soll ich einen Token deaktivieren oder löschen?

Deaktivieren ist der vorsichtige Weg: Der Eintrag bleibt mit dem Kennzeichen Widerrufen in der Liste stehen, 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. Für beides gilt: Der Zugriff endet sofort, beides steht im Audit-Log, und beides wird per E-Mail gemeldet.

Kann ich IPv6-Adressen eintragen?

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.

Sehe ich hier nur meine eigenen Tokens?

Nein. Die Liste unter Organisation › Einstellungen › Entwickler › API zeigt alle API-Tokens deiner Organisation, unabhängig davon, wer sie angelegt hat.

Warum bekommt jemand eine E-Mail, wenn ich einen Token anlege?

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 den 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 ebenfalls. So fällt auf, wenn jemand anders gehandelt hat.

Wer hat einen Token angelegt oder gelöscht?

Jedes Anlegen, Ändern, Kopieren, Deaktivieren, Neu-Erzeugen und Löschen wird protokolliert. Nachlesen kannst du es unter Organisation › Audit-Log im Protokoll Einstellungen.