API-Schlüssel: Ein anderes System mit deinem Studio verbinden

Was ist das

Mit einem API-Schlüssel kann ein anderes System (ein ERP, eine automatische Tabelle, eine Website oder eine eigene App) Daten deines Studios abrufen und speichern, ohne dass jemand etwas eingeben muss. Jeder Schlüssel verhält sich wie ein Benutzer des Studios: Er kann genau das, was dieser Benutzer darf, und nichts darüber hinaus.

Wann verwenden

Ein Verwaltungssystem muss die Tagesumsätze für die Buchhaltung auslesen.
Eine eigene Website oder App muss Kunden anlegen oder den Katalog abrufen.
Eine Automatisierung muss Ausgaben erfassen oder offene Forderungen abrufen.

Bevor Sie beginnen

Nur wer das Studio verwaltet (mit Vollzugriff oder der Berechtigung, Profile und Benutzer zu bearbeiten), kann Schlüssel erstellen, bearbeiten und widerrufen. Wenn du keinen Schlüssel erstellen kannst, bitte den Studiobesitzer, deinen Zugriff unter Zugriffe → Profile freizugeben.

Wir empfehlen, zuerst einen eigenen Benutzer für die Integration anzulegen und ihm ein Profil zuzuweisen, das nur die Bereiche freigibt, die das andere System benötigt. Der Schlüssel übernimmt die Berechtigungen dieses Benutzers.

Schritt für Schritt

Schritt 1 — Den Tab „API Key“ öffnen

Öffne unter Einstellungen → Unternehmen den Tab API Key. Dort werden alle erstellten Schlüssel sowie der jeweilige Benutzer, die Erlaubte IPs, die Gültigkeit und die Angabe Zuletzt verwendet angezeigt.

Tab „API Key“ mit der Liste der Schlüssel

Schritt 2 — Einen Schlüssel erstellen

Klicke auf Neuer Schlüssel, gib einen Name ein und wähle den Benutzer aus. Trage unter Erlaubte IPs pro Zeile eine IP-Adresse oder einen IP-Bereich ein, damit nur Anfragen von diesen Adressen akzeptiert werden. Wenn das Feld leer bleibt, sind alle IP-Adressen zugelassen. Wähle unter Gültigkeit entweder Läuft nie ab oder Läuft ab am und lege ein Datum fest. Der Schlüssel ist bis zum Ende dieses Tages gültig. Klicke auf Schlüssel erstellen und kopiere den Schlüssel über die Schaltfläche zum Kopieren. Er wird nicht noch einmal angezeigt.

Das andere System muss den Schlüssel bei jeder Anfrage im Header Authorization mitsenden, und zwar so: Authorization: Bearer hk_... (setze den vollständigen Schlüssel anstelle von hk_... ein).

Wenn du den Schlüssel mit einer KI (Claude Code, Gemini CLI, Cursor) verwenden möchtest, aktiviere unter KI-Konnektor auch Verwendung als KI-Konnektor erlauben. Ohne diese Option funktioniert der Schlüssel zwar für Integrationen, aber nicht mit dem KI-Konnektor. Weitere Informationen findest du im Artikel KI-Konnektor.

Ausgefülltes Formular zum Erstellen eines neuen API-Schlüssels

Schritt 3 — Einen Schlüssel widerrufen

Klicke in der Liste auf das Papierkorbsymbol des Schlüssels und bestätige mit Widerrufen. Das System, das den Schlüssel verwendet hat, verliert innerhalb von 30 Sekunden den Zugriff. Um den Namen, die IP-Adressen oder die Gültigkeit zu ändern, klicke auf das Stiftsymbol.

Bestätigung zum Widerrufen eines API-Schlüssels

Was danach passiert

Alle Änderungen, die das andere System mit dem Schlüssel vornimmt, erscheinen in der Prüfprotokoll mit der Herkunft API-Schlüssel und dem Namen des Benutzers, dem der Schlüssel gehört.
Der Schlüssel funktioniert nicht mehr, sobald seine Gültigkeit abläuft oder der zugehörige Benutzer im Studio deaktiviert wird. In der Liste wird er dann als Abgelaufen oder Inaktiver Benutzer angezeigt.
Ein Schlüssel gewährt niemals Zugriff auf ein anderes Unternehmen, auch wenn der zugehörige Benutzer dort ebenfalls arbeitet.

Häufige Fehler und Fragen

F: Kann der Schlüssel alles im System tun? A: Nein. Er verfügt nur über die Berechtigungen des zugehörigen Benutzers und gilt nur für dieses Studio. In einigen Bereichen sind Schlüssel grundsätzlich nicht zulässig, auch nicht für Benutzer mit Vollzugriff: Anmeldung und Unternehmenswechsel, die Schlüsselverwaltung selbst, die Benutzer- und Einladungsverwaltung, Heya, der Support, die Dashboards, die allgemeinen Unternehmenseinstellungen (Logo, Öffnungszeiten, Feiertage, Domain, E-Mail-Adresse für Berichte) sowie die Plattformbereiche. Wenn du mehrere Integrationen nutzt, lege für jede einen eigenen Benutzer an. In der Prüfprotokoll erscheinen Änderungen unter dem Namen des Benutzers, dem der Schlüssel gehört.

F: Ich habe den Schlüssel verloren. Kann ich ihn noch einmal anzeigen lassen? A: Nein. Das System speichert nur einen Fingerabdruck des Schlüssels, niemals den Schlüssel selbst. Widerrufe den alten Schlüssel und erstelle einen neuen.

F: Das andere System erhält die Meldung „Diese IP ist nicht berechtigt, diesen API-Schlüssel zu verwenden.“ Was soll ich tun? A: Die IP-Adresse, von der aus das System die Anfrage sendet, ist nicht unter Erlaubte IPs eingetragen. Bearbeite den Schlüssel und füge die IP-Adresse hinzu oder lasse die Liste leer, um alle IP-Adressen zuzulassen.

F: Das andere System erhält die Meldung „Diese Route kann nicht mit einem API-Schlüssel verwendet werden.“ Warum? A: Es greift auf einen Bereich zu, in dem Schlüssel nicht zulässig sind (siehe erste Frage). Diese Vorgänge müssen von einer Person direkt in der Anwendung ausgeführt werden.

F: Kann ich den Benutzer eines Schlüssels ändern? A: Nein. Widerrufe den Schlüssel und erstelle einen neuen für den anderen Benutzer.

F: Die Benutzerliste beim Erstellen eines neuen Schlüssels ist leer. Warum? A: Benutzer des Plattformteams können keinen API-Schlüssel haben und werden deshalb nicht in der Liste angezeigt. Lege einen Benutzer für dein eigenes Studio an (am besten einen eigenen Benutzer für die Integration) und erstelle den Schlüssel für ihn.