# API und Schlüssel (https://docs.akollo.com/de/connections/api)



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 [#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-schlüssel-anlegen]

<Steps>
  <Step>
    ### API keys öffnen [#api-keys-öffnen]

    Öffnen Sie **Integrations → API keys** und dort das Formular zum Anlegen eines Schlüssels.
  </Step>

  <Step>
    ### Namen vergeben und Dienstkonto wählen [#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.
  </Step>

  <Step>
    ### Berechtigungen wählen [#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.
  </Step>

  <Step>
    ### Ablaufdatum und Adressen festlegen [#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.
  </Step>

  <Step>
    ### Schlüssel anlegen und sichern [#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_`.
  </Step>
</Steps>

<Callout type="info" title="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.
</Callout>

### Schlüssel erneuern oder widerrufen [#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.

<Steps>
  <Step>
    ### Schlüssel suchen [#schlüssel-suchen]

    Suchen Sie den Schlüssel in der Liste unter **Integrations → API keys**.
  </Step>

  <Step>
    ### Mit Begründung widerrufen [#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**.
  </Step>
</Steps>

## Die öffentliche API [#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 [#anfragen-wiederholungen-und-limits]

Ein schreibender Aufruf sendet einen `Idempotency-Key`. So kann ein Programm eine Anfrage nach einer Zeitüberschreitung gefahrlos wiederholen.

<Mermaid
  title="Wie ein wiederholter Schreibaufruf behandelt wird"
  chart="`sequenceDiagram
participant P as Programm
participant A as Akollo
P->>A: Schreiben mit Idempotency-Key und Inhalt
A-->>P: Erste Antwort
P->>A: Gleicher Schlüssel, gleicher Inhalt binnen 24 Stunden
A-->>P: Wieder die erste Antwort
P->>A: Gleicher Schlüssel, anderer Inhalt
A-->>P: Abgelehnt`"
/>

| 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 [#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 [#häufige-fragen]

<Accordions type="single">
  <Accordion title="Ich habe einen API-Schlüssel verloren. Kann ich ihn erneut ansehen?">
    Nein. Ein Schlüssel wird nur einmal angezeigt. Erneuern Sie ihn mit **Roll**; der bisherige Schlüssel funktioniert noch eine kurze Übergangszeit.
  </Accordion>

  <Accordion title="Warum wartet mein neuer Schlüssel auf Freigabe?">
    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.
  </Accordion>

  <Accordion title="Kann ein Schlüssel mehr als sein Dienstkonto?">
    Nein. Was ein Schlüssel darf, ist immer auf die Rolle seines Dienstkontos begrenzt.
  </Accordion>

  <Accordion title="Darf ich einen Schreibaufruf nach einer Zeitüberschreitung wiederholen?">
    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.
  </Accordion>

  <Accordion title="Was passiert bei zu vielen Aufrufen?">
    Jeder Aufrufer hat ein Limit pro Minute. Ist es erreicht, nennt die Antwort, wann ein neuer Versuch möglich ist.
  </Accordion>
</Accordions>

## Verwandte Seiten [#verwandte-seiten]

* [BI-Datensätze](/de/connections/bi-datasets)
* [Webhooks](/de/connections/webhooks)
* [Verbundene Systeme](/de/connections)