API-Schlüssel
API-Schlüssel für die REST-API von ZepDesk anlegen, umstellen und widerrufen. Jeder Schlüssel bekommt eine Vorlage für seine Rechte. Das Secret sehen Sie nur einmal.
Mit einem API-Schlüssel greifen eigene Programme, Make, Zapier und andere Werkzeuge auf die REST-API Ihrer ZepDesk-Instanz zu. Ein Schlüssel gilt für die Firma, in der er angelegt ist.
Rechte
Jeder neue Schlüssel bekommt beim Anlegen eine Vorlage für seine Rechte: Buchhaltung, Vertrieb, Steuer oder Nur-Lesen. Einzelne Rechte können Sie über die API davon abweichend setzen. Webhooks, API-Schlüssel, OAuth, Integrationen, Erweiterungen und Benutzer kann kein Schlüssel verwalten. Schlüssel aus der Zeit vor den Vorlagen hat ZepDesk auf die Vorlage Buchhaltung umgestellt; die Verwaltung Ihrer Firma hat dazu eine Mitteilung erhalten. Geben Sie einen Schlüssel nur an Systeme, denen Sie das zutrauen.
API-Schlüssel anlegen
Schlüssel legt die Rolle Verwaltung an:
- Öffnen Sie Hilfe & Glossar → Schnittstelle, Ansicht Zugang.
- Geben Sie eine Bezeichnung ein, etwa „Zapier“ oder „Buchhaltungssoftware“.
- Wählen Sie die Vorlage. Ohne Vorlage bleibt Erzeugen gesperrt. Nehmen Sie die Vorlage mit den wenigsten Rechten, mit der die Anwendung auskommt. Soll sie nur lesen, wählen Sie Nur-Lesen.
- Klicken Sie auf Erzeugen.
ZepDesk zeigt danach API-Key, API-Secret und den fertigen Kopf für die Anmeldung, und zwar nur einmal. Kopieren Sie beides sofort, etwa in einen Passwort-Manager. In der Liste steht der Schlüssel danach nur noch gekürzt.
Jeder Aufruf meldet sich mit diesem Kopf an:
Authorization: token <API-Key>:<API-Secret>
Vorlage eines Schlüssels umstellen
Die Rolle Verwaltung wählt in der Liste beim Schlüssel eine andere Vorlage und bestätigt mit Umstellen. Der Schlüssel arbeitet danach mit den Rechten dieser Vorlage. Das Secret bleibt gültig; in der Anwendung ändern Sie nichts.
Schlüssel aus der Zeit vor den Vorlagen arbeiten seit der Umstellung mit der Vorlage Buchhaltung. Prüfen Sie, ob diese Vorlage zur Anwendung passt, und stellen Sie sie bei Bedarf wie oben um.
API-Schlüssel widerrufen
Klicken Sie in der Liste beim Schlüssel auf Widerrufen. Anbindungen, die ihn benutzen, verlieren sofort den Zugriff. Der Schlüssel verschwindet danach aus der Liste. Widerrufen lässt sich nicht rückgängig machen; legen Sie bei Bedarf einen neuen an.
Developer-Apps
Wie Sie eine Developer-App verbinden und wo Sie den Zugriff wieder entziehen, steht unter Developer-Apps verbinden.
Wo finde ich die vollständige API-Referenz?
Ihre Instanz zeigt die Referenz unter Hilfe & Glossar → Schnittstelle, Ansicht Referenz, mit allen Endpunkten Ihrer Fassung, ihren Parametern und Antworten. Dieselbe Spezifikation liegt öffentlich unter zepdesk.de/api, im Stand der letzten Veröffentlichung der Website.
Webhooks, mit denen ZepDesk Ihre Systeme über Ereignisse benachrichtigt, beschreibt das Kapitel Webhooks.
Empfehlungen
- Ein Schlüssel je Anwendung: dann widerrufen Sie eine Anbindung, ohne die anderen zu treffen.
- Regelmäßig wechseln: neuen Schlüssel anlegen, in der Anwendung eintragen, den alten widerrufen.
- Nicht im Quellcode ablegen: Schlüssel gehören in Umgebungsvariablen oder einen Tresor für Geheimnisse.
- Nur HTTPS: die API nimmt Anfragen nur über HTTPS an.