FlexiProject bietet eine REST-API, über die ein anderes System die Daten der Organisation lesen und ändern kann — um einen BI-Bericht zu speisen, Projekte mit einem ERP-System zu synchronisieren oder eine sich wiederholende Aufgabe zu automatisieren. Die vollständige Beschreibung der Endpunkte finden Sie unter developers.flexi-project.com.

Für Aufrufe der API benötigen Sie ein persönliches Zugriffstoken (API-Token). Sie erstellen es selbst in Ihrem Profil auf der Registerkarte API, und es arbeitet mit Ihren Berechtigungen: Die API zeigt genau die Daten, die Sie in der Anwendung sehen, und nichts darüber hinaus.

Persönliches Zugriffstoken

Wer ein Token erstellen kann

Ein Token für das eigene Konto erstellen Benutzer mit der Lizenz Voll (siehe Lizenzen) sowie Systemadministratoren; die Registerkarte API ist nur für sie sichtbar. Eine Administratorberechtigung ist nicht nötig. Das Token trägt die Berechtigungen seines Eigentümers, es erreicht also dieselben Projekte und Felder, die der Eigentümer in der Anwendung sieht. Zwei Personen mit unterschiedlichen Rollen erhalten bei derselben Anfrage unterschiedliche Ergebnisse.

Ein Token funktioniert nicht mehr, wenn das Konto deaktiviert, aus der Organisation entfernt oder gesperrt wird. Sie müssen Token also nicht aufräumen, wenn jemand das Unternehmen verlässt.

Token erstellen

1. Öffnen Sie das Avatar-Menü, wählen Sie Benutzerprofil und wechseln Sie zur Registerkarte API (siehe Benutzerprofil).
2. Klicken Sie auf Neues Token.
3. Geben Sie im Feld Name einen Namen ein — höchstens 100 Zeichen. Der Name sollte angeben, welcher Integration das Token dient, denn nur daran erkennen Sie Ihre Token später.
4. Legen Sie das Ablaufdatum fest. Frühestens ist es morgen, spätestens 365 Tage ab heute; das Feld wird mit 30 Tagen geöffnet. Das Token läuft am Ende des gewählten Tages ab.
5. Klicken Sie auf Token erstellen.

Token sofort kopieren

Das Fenster Persönliches Zugriffstoken wurde erstellt zeigt den vollständigen Wert nur einmal an, mit einem Hinweis: Kopieren Sie das Token und bewahren Sie es an einem sicheren Ort auf — nach dem Schließen dieses Fensters kann es nicht mehr eingesehen werden. Die Schaltfläche Kopieren kopiert den Wert in die Zwischenablage, und Sie fügen ihn direkt in das System ein, das ihn verwenden wird. Nach dem Schließen des Fensters kann den Wert niemand mehr wiederherstellen — weder Sie noch ein Administrator noch der Support. Wenn Sie ein Token verlieren, löschen Sie es und erstellen Sie ein neues.

Token-Liste

Die Registerkarte API listet Ihre Token in den Spalten Name, Token, Erstellt am und Läuft ab auf. Die Spalte Token zeigt nur die ersten Zeichen des Werts — genug, um ein Token dem in einer Integration gespeicherten zuzuordnen.

Die Spalte Läuft ab warnt rechtzeitig: Ein Token, das innerhalb von sieben Tagen abläuft, trägt ein Etikett mit der Zahl der verbleibenden Tage, ein heute ablaufendes zeigt läuft heute ab, und ein abgelaufenes zeigt abgelaufen. Ein abgelaufenes Token bleibt in der Liste, bis Sie es löschen, authentifiziert aber nichts mehr.

Sie können gleichzeitig bis zu zehn aktive Token haben. Ist das Limit erreicht, verweigert die Anwendung das Erstellen eines weiteren mit der Meldung Sie haben bereits 10 aktive persönliche Zugriffstoken. Löschen Sie ein nicht verwendetes Token, um ein neues zu erstellen. Abgelaufene Token zählen nicht zum Limit.

Token löschen

Das Papierkorb-Symbol in der Zeile eines Tokens löscht es nach einer Bestätigung. Die Anwendung warnt mit dem Satz Integrationen, die es verwenden, funktionieren sofort nicht mehr — und so ist es auch: bei ihrer nächsten Anfrage. Das Löschen kann nicht rückgängig gemacht werden; ein Token zu ersetzen bedeutet immer ein neues Token mit einem neuen Wert.

Token verwenden

Ein API-Token wird nicht mit jeder Anfrage gesendet. Sie tauschen es einmal gegen ein Zugriffstoken ein und verwenden dieses von da an.

Senden Sie ein POST an /api/user/token/personal mit Ihrer E-Mail-Adresse und dem Wert des Tokens:

POST /api/user/token/personal
Content-Type: application/json

{ "email": "anna.kowalska@example.com", "token": "fpat_…" }

Die Antwort enthält das access_token, seinen Typ, die Kennung der Organisation, zu der das Token gehört, und die Anzahl der Sekunden, die es gültig ist. Senden Sie das Zugriffstoken im Header Authorization der folgenden Aufrufe und wiederholen Sie den Austausch, wenn es abläuft.

Die E-Mail-Adresse muss zu dem Konto gehören, das das Token erstellt hat, und das Token selbst bestimmt, in welche Organisation Sie gelangen — wenn Sie in mehreren arbeiten, erstellen Sie in jeder ein eigenes Token.

Wiederholte fehlgeschlagene Versuche sind begrenzt: Nach zehn fehlgeschlagenen Versuchen für dieselbe E-Mail-Adresse werden weitere fünfzehn Minuten lang abgelehnt. Wenn eine Integration plötzlich massenhaft Ablehnungen erhält, prüfen Sie den gespeicherten Wert, statt es in einer Schleife erneut zu versuchen.

Der Austausch eines API-Tokens funktioniert auch, wenn die Anmeldung per Passwort ausgeschaltet ist, weil sich dabei keine Person anmeldet (siehe Anmeldemethoden).