17. Integrations-API und API-Schlüssel

Die Integrations-API ermöglicht es deinem eigenen Programm, deiner Tabelle oder deinem Skript, die Daten deiner Projekte maschinell auszulesen: die Projektliste, die Kabel- und Materialliste, die Stromkreistabelle und die Klemmenliste der Verteiler, die Mengenauswertung und die Zusammenstellung des Planpakets. Die API liest nur: Sie verändert weder die Zeichnung noch das Projekt.

Wer einen API-Schlüssel bekommen kann

Den API-Schlüssel schaltet der Betreiber pro Konto frei. Hat dein Konto die Freigabe erhalten, erscheint auf der Seite Profil die Karte API-Schlüssel; ohne Freigabe ist die Karte nicht sichtbar. Ein Konto kann höchstens 5 aktive Schlüssel gleichzeitig haben.

Der Schlüssel sieht dieselben Projekte wie du: deine eigenen und auf Anfrage die, die mit dir geteilt wurden. Listen und Auswertung eines geteilten Projekts gibt er nur dann heraus, wenn die Freigabe auch den Export erlaubt.

Schlüssel erstellen

Klicke auf der Karte API-Schlüssel der Seite Profil auf Neuer Schlüssel.
Gib dem Schlüssel einen Namen (zum Beispiel den Namen des Programms, das ihn verwenden wird).
Wähle die Berechtigung: Projekte lesen liefert die Projektliste und die Projektdaten, Dokumente lesen liefert die Listen, die Auswertung und das Planpaket. Gib nur das an, was das Programm wirklich braucht.
Wähle den Ablauf: 30, 90 oder 365 Tage. Ein abgelaufener Schlüssel funktioniert nicht mehr; erstelle stattdessen einen neuen.
Gib dein aktuelles Passwort ein (bei einem Konto ohne Passwort ist eine frische Anmeldung nötig). Beim ersten Schlüssel akzeptiere die Bedingungen der API-Nutzung.

Nach dem Erstellen wird der Schlüssel nur ein einziges Mal angezeigt: Kopiere ihn und bewahre ihn an einem sicheren Ort auf. Später zeigt die Liste nur sein Präfix (avk_…), mit Erstellungs- und Ablaufdatum, letzter Nutzung und Anzahl der Aufrufe. Über den neuen Schlüssel senden wir außerdem eine E-Mail-Benachrichtigung (ohne den Schlüssel selbst).

Schlüssel widerrufen

Mit der Schaltfläche Widerrufen neben dem Schlüssel wird er sofort unbrauchbar; das lässt sich nicht rückgängig machen. Widerrufe den Schlüssel, wenn du ihn nicht mehr verwendest, wenn du das Programm einstellst, das ihn genutzt hat, oder wenn du vermutest, dass er in falsche Hände geraten ist.

Sicherheitshinweise

Behandle den Schlüssel wie dein Passwort: Wer ihn kennt, kann im vergebenen Berechtigungsumfang deine Projekte lesen.
Bewahre ihn in einem Geheimnisspeicher auf (Passwortmanager, Umgebungsvariable des Servers oder geheime Variable der CI), nicht im Quellcode: Er darf nicht ins git-Repository, in eine geteilte Tabelle oder in eine E-Mail gelangen.
Verwende ihn nicht in Code, der im Browser läuft (Webseite, Browser-Erweiterung): Dort kann ihn jeder auslesen. Ein Schlüssel gehört auf einen Server, in ein Skript oder in ein Desktop-Programm.
Jedes Programm sollte einen eigenen Schlüssel haben, mit möglichst engem Berechtigungsumfang und kurzem Ablauf; so legt das Widerrufen eines Schlüssels nichts anderes lahm.

Verwendung aus einem Programm

Im Header der Anfrage wird der Schlüssel als Bearer-Token gesendet: Authorization: Bearer avk_…. Die Endpunkte liegen unter /api/v1/ (zum Beispiel GET /api/v1/projects), die Antwort ist JSON. Die genaue Beschreibung im OpenAPI-Format ist unter /api/v1/openapi.json abrufbar; die meisten Entwicklerwerkzeuge können sie einlesen.

Die Anzahl der Aufrufe ist pro Schlüssel und pro Konto begrenzt (standardmäßig 60 pro Minute und 10 000 pro Tag); bei Überschreitung antwortet der Server mit 429, warte dann einen Moment. Die Webanmeldung (Cookie) öffnet die API nicht, und ein Schlüssel meldet dich nicht an der Weboberfläche an.