API und Schlüssel
Andere Systeme greifen mit einem API-Schlüssel über die öffentliche API auf Akollo zu. Administratoren legen die Schlüssel an. Jeder Schlüssel trägt nur die Berechtigungen, die er braucht, und lässt sich jederzeit widerrufen.
API-Schlüssel
Integrations → API keys (API-Schlüssel) listet für jeden Schlüssel:
| Spalte | Inhalt |
|---|---|
| Name | Der Name, den Sie vergeben haben |
| Schlüssel | Die ersten Zeichen des Schlüssels |
| Service account | Das Dienstkonto, in dessen Namen der Schlüssel handelt |
| Scopes | Was der Schlüssel lesen darf |
| Expires | Das Ablaufdatum |
| Last used | Wann der Schlüssel zuletzt verwendet wurde |
| State | Waiting for approval, Active, Rolling, Revoked oder Expired |
Ein Schlüssel, der auf Freigabe wartet, zeigt an, wer ihn freigeben muss.
API-Schlüssel anlegen
API keys öffnen
Öffnen Sie Integrations → API keys und dort das Formular zum Anlegen eines Schlüssels.
Namen vergeben und Dienstkonto wählen
Geben Sie dem Schlüssel einen Namen, der das nutzende System erkennen lässt. Wählen Sie das Service account (Dienstkonto), in dessen Namen der Schlüssel handelt. Was ein Schlüssel darf, ist immer auf die Rolle seines Dienstkontos begrenzt.
Berechtigungen wählen
Setzen Sie jede benötigte Berechtigung unter Scopes auf Read und lassen Sie die übrigen auf None. Die Berechtigungen für Work items und Filters werden nur lesend angeboten.
Ablaufdatum und Adressen festlegen
Legen Sie ein Ablaufdatum fest; ein Schlüssel läuft innerhalb eines Jahres ab. Optional tragen Sie unter Allowed IP ranges die zulässigen IP-Bereiche ein, einen pro Zeile.
Schlüssel anlegen und sichern
Wählen Sie Create key. Der Schlüssel wird einmal angezeigt. Kopieren Sie ihn, bewahren Sie ihn sicher auf und bestätigen Sie, dass Sie ihn gespeichert haben. Er beginnt mit akl_live_ oder akl_test_.
Hinweis
Ein Schlüssel, der eine Freigabe braucht, etwa weil er Datensätze ändern kann, wartet, bis ein anderer Administrator ihn freigibt. Wer einen Schlüssel angelegt hat, kann ihn nicht selbst freigeben.
Schlüssel erneuern oder widerrufen
- Roll ersetzt einen Schlüssel. Der bisherige Schlüssel funktioniert noch eine kurze Übergangszeit, damit Sie das nutzende System umstellen können. Währenddessen zeigt der Schlüssel den Zustand Rolling.
- Revoke entzieht einen Schlüssel jederzeit.
Schlüssel suchen
Suchen Sie den Schlüssel in der Liste unter Integrations → API keys.
Mit Begründung widerrufen
Wählen Sie Revoke und geben Sie unter Reason eine Begründung ein. Der Zustand des Schlüssels wechselt auf Revoked.
Die öffentliche API
Programme rufen /api/public/v1 auf und senden im Header Akollo-Version das Datum der API-Version, für die sie entwickelt wurden.
- Mit einer Leseberechtigung kann ein Schlüssel Projekte, Aufgaben, erfasste Mitarbeitende und tägliche Zeitzusammenfassungen auflisten und einzeln abrufen.
- Die Berechtigungen für Work items und Filters erlauben zusätzlich, Arbeitselemente zu lesen und zu durchsuchen, gespeicherte Filter und Ansichten zu lesen sowie die Anhänge eines Arbeitselements aufzulisten und herunterzuladen.
- Listen liefern eine Seite mit Datensätzen und einen Cursor für die nächste Seite. Jede Liste akzeptiert eine Seitengröße, einen Cursor und einen Zeitpunkt, ab dem Änderungen gelesen werden.
- Ein fehlender Datensatz und ein Datensatz einer anderen Organisation sehen gleich aus.
- Eine Tageszusammenfassung wird nur geliefert, wenn der Aufrufer den Tag dieser Person sehen darf. Sie enthält das Datum, die gearbeitete und die angerechnete Zeit und ob der Wert noch aktuell ist. Aktivität, Aufnahmen und Aufteilung auf Aufgaben enthält sie nicht.
- Fehler sind Problem-Dokumente. Ein Fehler beschreibt nie einen Datensatz einer anderen Organisation.
- Dateien und CSV-Exporte werden unverändert mit ihrem eigenen Inhaltstyp geliefert.
Anfragen, Wiederholungen und Limits
Ein schreibender Aufruf sendet einen Idempotency-Key. So kann ein Programm eine Anfrage nach einer Zeitüberschreitung gefahrlos wiederholen.
| Situation | Ergebnis |
|---|---|
Gleicher Idempotency-Key und gleicher Inhalt innerhalb von 24 Stunden | Die erste Antwort wird geliefert; der Schreibvorgang läuft nicht erneut. |
Gleicher Idempotency-Key mit anderem Inhalt | Abgelehnt. |
| Erste Antwort größer als 64 KiB | Wird nicht gespeichert. Eine Wiederholung mit diesem Schlüssel wird abgelehnt und läuft nicht erneut. |
| Minutenlimit erreicht | Jeder Aufrufer hat ein Limit pro Minute. Die Antwort nennt, wann ein neuer Versuch möglich ist. |
Entwicklerreferenz
Die OpenAPI-Beschreibung der aktivierten Operationen liegt unter /api/public/v1/openapi.json (und .yaml).
Integrations → Developer (Entwickler) zeigt jede Route der gewählten Version mit der nötigen Berechtigung und einem curl-Beispiel. Der Schlüssel im Beispiel ist immer ein Platzhalter; die Seite sendet nie eine Anfrage mit einem echten Schlüssel. Abgekündigte Routen und Routen mit Abschaltdatum tragen eine Kennzeichnung. Routen eines deaktivierten Moduls werden nicht aufgeführt.
Häufige Fragen
Nein. Ein Schlüssel wird nur einmal angezeigt. Erneuern Sie ihn mit Roll; der bisherige Schlüssel funktioniert noch eine kurze Übergangszeit.
Ein Schlüssel, der eine Freigabe braucht, etwa weil er Datensätze ändern kann, wartet, bis ein anderer Administrator ihn freigibt. Wer ihn angelegt hat, kann ihn nicht selbst freigeben.
Nein. Was ein Schlüssel darf, ist immer auf die Rolle seines Dienstkontos begrenzt.
Ja, wenn Sie innerhalb von 24 Stunden denselben Idempotency-Key mit demselben Inhalt senden. Sie erhalten die erste Antwort, und der Schreibvorgang läuft nicht doppelt.
Jeder Aufrufer hat ein Limit pro Minute. Ist es erreicht, nennt die Antwort, wann ein neuer Versuch möglich ist.
Verwandte Seiten
Synchronisierung im Detail
Wie eine Verbindung Datensätze abgleicht: Gruppen und Verantwortliche, Zuordnung, Feldzuordnung, Probleme und an der Quelle gelöschte Datensätze.
Webhooks
Webhooks übertragen Ereignisse sofort: Eingehende Webhooks benachrichtigen Akollo, ausgehende Webhooks benachrichtigen ein anderes System.