Authentifizierung

Hier erklären wir dir, wie du einen API-Token erhältst, ihn an die i-Planner REST API v3 sendest, welche Scopes welche Endpoints freischalten und wie die API auf fehlerhafte oder abgelaufene Tokens reagiert.

Zuletzt geprüft: 14. September 2026

Überblick

Die i-Planner REST API v3 nutzt Bearer-Token-Authentifizierung über JWT. Jeder Request muss einen gültigen Token im Authorization-Header mitführen — sonst antwortet die API mit 401. Tokens sind organisationsgebunden: Ein Token gehört zu genau einer Organisation. Die API prüft bei jedem Aufruf die aktuell gespeicherten Berechtigungen, den Aktivierungsstatus, die Gültigkeit und die erlaubten IP-Adressen. Behandle den Token-String als undurchsichtiges Secret; seine JWT-Claims sind kein Berechtigungsnachweis für deine Anwendung. MCP-/OAuth-Tokens gelten nicht als REST-API-Tokens.

Es gibt kein OAuth-Flow, kein Refresh-Token, keine Cookie-Session für die REST-API — ein Token wird einmal im i-Planner-Account erzeugt, sicher gespeichert (Environment-Variable oder Secret-Manager) und für alle Server-zu-Server-Calls verwendet.

Token erzeugen

Tokens werden im i-Planner-UI deiner Organisation angelegt:

Organisation → Einstellungen → Tokens öffnen (/organization/settings/tokens).
Einen neuen Token anlegen und einen eindeutigen Namen vergeben, z. B. „CRM-Synchronisierung“.
Unter Berechtigungen die benötigten Datenbereiche wählen. Über + lassen sich weitere Bereiche ergänzen; je Bereich werden Lesen und, sofern unterstützt, Schreiben eingestellt. Neue Bereiche starten mit Lesen aktiviert und Schreiben deaktiviert. Der Posteingang unterstützt nur Schreiben.
Die Vorauswahl prüfen: Bei einem neuen Token sind die verfügbaren Leseberechtigungen vorausgewählt. Entferne alle Bereiche, die deine Integration nicht benötigt. Eine leere Berechtigungsliste erteilt keinen Datenzugriff. Schreiben umfasst Anlegen, Ändern und Löschen; Lesen muss bei Bedarf zusätzlich aktiviert sein.
Gültigkeit wählen: 1, 3 oder 6 Monate oder Unbegrenzt (Lifetime). Standard ist 3 Monate. Maßgeblich ist das angezeigte tatsächliche Ablaufdatum.
Optional IPs und weitere Empfänger unter E-Mail-Benachrichtigung ergänzen (siehe unten).
Den Token-String einmalig kopieren und sicher speichern. Er wird später nicht erneut angezeigt. Bei Verlust kann er regeneriert werden; der bisherige String wird dadurch sofort ungültig.

Token verwenden

Jeder Request trägt den Token als Authorization: Bearer <TOKEN> im Header:

http

Authorization: Bearer IPLANNER_API_TOKEN

curl https://www.api.i-planner.app/v3/customers \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

const res = await fetch('https://www.api.i-planner.app/v3/customers', {
  headers: {
    Authorization: `Bearer ${process.env.IPLANNER_API_TOKEN}`,
  },
})

import os, requests

res = requests.get(
    'https://www.api.i-planner.app/v3/customers',
    headers={'Authorization': f'Bearer {os.environ["IPLANNER_API_TOKEN"]}'},
)

<?php
$ch = curl_init('https://www.api.i-planner.app/v3/customers');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('IPLANNER_API_TOKEN'),
  ],
]);
$response = curl_exec($ch);

Scopes

Jeder Endpoint verlangt einen Scope nach dem Muster v3:<resource>:<action>. Der Token muss diesen Scope freigeschaltet haben, sonst kommt HTTP 403.

Kern-Konvention: Der Scope hängt an den Daten, nicht am URL-Pfad — z. B. /v3/customers/{kid}/contracts braucht v3:contracts:read bzw. v3:contracts:write, nicht den Customer-Scope. Jede eigenständige Ressourcen-Familie hat ihre eigene Scope-Familie.

Direkte Customer-Sub-Ressourcen (addresses, contacts, banking, numbers, identity, jobs, plus comments / followers / tags / links / relations) gehören dagegen zur Customer-Familie und sind über v3:customers:read|write abgedeckt — sie sind keine eigenständigen Daten-Domänen, sondern Felder am Customer-Datensatz.

Eigene Scope-Familien (orthogonal zur Customer-Familie):

v3:contracts:* — Verträge (auch unter /v3/customers/{kid}/contracts)
v3:damages:* — Schäden
v3:finances:* — Finanzen
v3:goals:* — Ziele
v3:documents:* — Dokumente (cross-resource)
v3:activities:* — Aktivitäten
v3:products:* — Produktpartner, Portale und Ansprechpartner
v3:users:* — Mitarbeiter

Actions: read für Lesen und write für Änderungen. Einige Familien haben nur eine Action: Die Suche benötigt trotz POST ausschließlich v3:search:read, der Posteingang ausschließlich v3:inbox:write. * in dieser Doku ist eine Kurzschreibweise für die verfügbaren Actions und kein gültiger Token-Scope. Den genauen Scope jedes Aufrufs zeigt die Endpoint-Übersicht.

Ein Customer-Scope deckt nicht automatisch Verträge, Schäden, Finanzen, Ziele, Dokumente oder Aktivitäten ab — diese haben eigene Scope-Familien, auch wenn der URL-Pfad mit /v3/customers/... beginnt.

Token-Ablauf

Die Gültigkeit wird am gespeicherten Token geprüft. Bei neu in v5 erzeugten REST-Tokens kannst du sie ändern, ohne den Token-String auszutauschen: Eine Verlängerung stellt den Zugriff wieder her, sobald die neue Gültigkeit gespeichert ist und der Token aktiv ist. Ältere Tokens mit einem eigenen Ablauf-Claim können zusätzlich durch diesen Claim begrenzt bleiben; regeneriere sie nach einer Verlängerung.

X-Token-Expires-At — ISO-Zeitstempel der wirksamen Gültigkeit, sobald die Token-Prüfung erfolgreich abgeschlossen ist. Bei unbegrenzten v5-Tokens entfällt der Header.
X-Token-Expires-In-Days — verbleibende volle Tage, nur bei höchstens 30 vollen Tagen Restlaufzeit. 0 bedeutet weniger als einen Tag; der Token bleibt bis zum tatsächlichen Ablaufzeitpunkt gültig.

Ein abgelaufener Token liefert 401 token_expired. Diese abgewiesene Anfrage enthält keine Token-Ablaufheader. Die Organisation muss weiterhin zugangsberechtigt und der ausstellende Benutzer weiterhin aktives Mitglied sein.

Aktivieren und regenerieren

Deaktivieren sperrt weitere Aufrufe sofort (401 token_revoked). Aktivieren erlaubt die Verwendung wieder, sofern die Gültigkeit, die IP-Freigaben und der Organisationszugang weiterhin passen. Aktivieren verlängert keinen abgelaufenen Token.

Regenerieren erzeugt einen neuen Token-String mit denselben Berechtigungen und demselben Ablaufdatum und aktiviert den Token. Der alte String wird sofort ungültig (401 token_not_found). Kopiere den neuen String aus der einmaligen Anzeige und hinterlege ihn in deiner Integration. Verlängere bei einem abgelaufenen Token zusätzlich seine Gültigkeit.

Für eine Rotation mit Übergangszeit lege einen separaten neuen Token an, stelle die Integration um und deaktiviere anschließend den alten. Regenerieren bietet keine Übergangszeit mit zwei gültigen Strings.

Erlaubte IP-Adressen

Unter IPs lassen sich über + einzelne IPv4-Adressen oder IPv4-Netze in CIDR-Notation eintragen, z. B. 203.0.113.7 oder 203.0.113.0/24. IPv6-Einträge werden im Token-Editor nicht unterstützt. Eine leere Liste bedeutet keine IP-Einschränkung.

Trage die öffentliche Ausgangsadresse deiner Integration ein. Passt die vom API-Server ermittelte Client-IP zu keinem Eintrag, liefert die API 403 ip_not_allowed. Änderungen gelten ab dem nächsten Aufruf; der Token-String bleibt gleich.

E-Mail-Benachrichtigungen

Der Inhaber der Organisation erhält Sicherheitsmeldungen auch ohne zusätzliche Empfänger. Unter E-Mail-Benachrichtigung kannst du über + weitere gültige E-Mail-Adressen für diesen Token hinterlegen. Doppelte Empfänger werden zusammengeführt; die Nachrichten enthalten keinen Token-String.

Erstellung, Kopie, Aktivierung, Deaktivierung, Regenerierung und Löschung: Änderungen am selben Token werden gebündelt. Die Meldung wird nach einer Minute ohne weitere Änderung, spätestens fünf Minuten nach der ersten Änderung, zum Versand vorgemerkt und anschließend versendet. Bei mehreren schnellen Zustandswechseln enthält sie den letzten Zustand.
Ablauf: Aktive REST-Tokens werden regelmäßig auch ohne neue API-Aufrufe geprüft. Eine Ablaufmeldung erfolgt einmal je tatsächlichem Ablaufdatum. Nach einer Verlängerung kann beim neuen Ablauf erneut eine Meldung erfolgen.
Fehlgeschlagene API-Aufrufe: Meldungen zu Fehlern nach erfolgreicher Token-Prüfung sowie zu abgewiesenen IP-Adressen werden auf eine Meldung pro Token innerhalb von 24 Stunden begrenzt. Fehlende oder ungültige Bearer-Tokens lösen keine solchen Token-Meldungen aus.
REST-API-Limit: Beim Erreichen des Organisationslimits erhält der betroffene Token eine gesonderte Meldung, höchstens einmal innerhalb von 24 Stunden. Die Wartezeit steht im API-Response (siehe Rate Limits).

Fehler bei Authentifizierung

Reguläre Auth-Fehler liefern ihre Fehlerdetails im JSON-Feld data des Responses ({ statusCode, statusMessage, data: { error, message, … } }). Die folgenden Beispiele zeigen die Fehlerdetails aus data. Defensive Clients können zusätzlich flache Fehlerdetails verarbeiten; siehe Fehler-Envelope. Eine vollständige Übersicht aller HTTP-Statuscodes der API steht in der Errors-Doku.

401 Unauthorized — Token-Probleme:

json

{
  "error": "missing_bearer_token",
  "message": "Authorization header must contain a Bearer token."
}

{
  "error": "empty_token",
  "message": "Bearer token is empty."
}

{
  "error": "invalid_token",
  "message": "The provided Bearer token is invalid or expired."
}

{
  "error": "token_expired",
  "message": "The API token has expired."
}

Weitere mögliche 401-Codes:

`error`	Bedeutung
`token_revoked`	Token deaktiviert.
`token_not_found`	Token gelöscht, String durch Regenerierung ersetzt oder kein nutzbarer Token für diesen Organisationsbenutzer vorhanden.
`wrong_token_kind`	Ein anderer Token-Typ wurde statt eines REST-Tokens verwendet.
`invalid_token_type`	Der JWT besitzt nicht die erforderliche API-Token-Struktur.
`token_mismatch`	Token und gespeicherte Zuordnung passen nicht zusammen.
`invalid_expiry`	Die gespeicherte oder im alten Token enthaltene Gültigkeit ist ungültig.
`missing_cid`	Für die Organisation ist kein API-Datenzugang zugeordnet.

403 Forbidden — Zugriff verweigert. Mögliche error-Codes:

`error`	Bedeutung
`missing_required_scope`	Fehlender Scope — der Token hat den vom Endpoint verlangten Scope nicht freigeschaltet. Das Feld `required_scope` im Response nennt ihn.
`ip_not_allowed`	Nicht erlaubte IP — die Client-IP passt zu keinem Eintrag unter Erlaubte IP-Adressen.
`contract_inactive`	Gesperrter Organisationszugang — der Vertrag der Organisation ist nicht aktiv.
`trial_expired`	Gesperrter Organisationszugang — die Testphase der Organisation ist abgelaufen.

Beispiel für einen fehlenden Scope:

json

{
  "error": "missing_required_scope",
  "message": "The endpoint \"/v3/customers\" requires the \"v3:customers:read\" scope.",
  "required_scope": "v3:customers:read",
  "provided_scope": "v3:customers:read = 0",
  "hint": "Ask your organization admin to enable 'v3:customers:read'."
}

429 Too Many Requests — Organisationslimit oder Schutz gegen wiederholte Authentifizierungsfehler, siehe Rate Limits in der Overview. Wiederholt fehlschlagende Auth-Versuche werden pro Client-IP gedrosselt:

json

{
  "error": "too_many_auth_failures",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retry_after": 60
}

Sicherheits-Empfehlungen

Tokens nur serverseitig halten — niemals im Browser, niemals in Mobile-Apps, niemals in Git-Repos.
Pro Integration ein eigener Token — bei Kompromittierung kann gezielt nur dieser revoked werden, ohne andere Workflows zu stören.
Minimale Scopes — nicht jeder Token braucht write auf alle Ressourcen.
Token-Namen sprechend wählen — bei Audit-Log oder Revocation weiß man dann sofort welcher zu welcher App gehört.
Tokens nicht per query mitschicken — die API akzeptiert das nicht, und Webserver loggen Query-Params häufig in Plain-Text. Nur über den Authorization-Header.
HTTPS verwenden — sende Tokens ausschließlich an die dokumentierte HTTPS-Basis-URL. Verlasse dich beim Senden eines Secrets nicht auf eine spätere HTTP-Umleitung.