# API-Tokens
> Wie du einen Zugangsschlüssel für die REST-API 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 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](/organisation/einstellungen/team-und-rollen/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:
| Punkt | Bedeutung |
|---|---|
| Grün, pulsierend | Der Token wurde schon mindestens einmal verwendet |
| Rot | Der Token wurde noch nie verwendet |
Rechts steht ein Kennzeichen zum Zustand:
| Kennzeichen | Bedeutung |
|---|---|
| **Widerrufen** (rot) | Der Token wurde deaktiviert und funktioniert nicht, bis er wieder aktiviert wird |
| **Abgelaufen** (gelb) | Die Laufzeit ist vorbei |
| **Unbegrenzt** | Für den Token ist keine Laufzeit eingestellt |
| **noch … Tage**, zum Beispiel **noch 14 Tage** (bei einem Tag **noch 1 Tag**) | So viele Tage dauert die eingestellte Laufzeit noch |
## 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**.
::callout
---
icon: i-heroicons-exclamation-triangle
color: amber
---
Behandle den Token wie ein Passwort. Er wird genau einmal angezeigt; danach siehst du nur noch einen Ausschnitt aus Anfang und Ende — auf der Bearbeiten-Seite im Bereich **Token** unter **Vorschau**. Wer den Token hat, arbeitet mit genau den Rechten, die du ihm gegeben hast.
::
Ü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**.
| 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 \. 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ü**:
| 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. |
| **Deaktivieren** | Sperrt den Token, siehe Abschnitt **Token deaktivieren und wieder aktivieren**. |
| **Löschen** | Entfernt den Eintrag endgültig. Die Rückfrage **Eintrag löschen?** bestätigst du mit **Löschen**. |
::callout
---
icon: i-heroicons-exclamation-triangle
color: amber
---
**Löschen lässt sich nicht rückgängig machen.** Programme, die den Token verwenden, haben ab sofort keinen Zugriff mehr, und der Schlüssel lässt sich nicht wiederherstellen. Willst du den Token später vielleicht wieder nutzen, deaktiviere ihn stattdessen.
::
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**.