OuiHeberg-API: API-Schlüssel erstellen und erste Aufrufe senden

Der OuiHeberg-Kundenbereich hat eine eigene API. Mit einem API-Schlüssel kann ein Skript oder eine Software Ihr Konto abfragen, ohne die Oberfläche zu nutzen, etwa um Ihre Domains oder Rechnungen im Blick zu behalten. Diese Anleitung zeigt, wo Sie einen Schlüssel erstellen, wie Sie die Dokumentation lesen, einen ersten Aufruf senden, die Aufruflimits beachten und einen Schlüssel widerrufen.

Den Bereich API-Schlüssel öffnen

Melden Sie sich auf dash.ouiheberg.com an.
Klicken Sie oben rechts auf Ihren Namen und dann auf Mein Profil.
Wählen Sie im Menü der Seite Kontoeinstellungen den Punkt API-Schlüssel.

Der direkte Link lautet dash.ouiheberg.com/settings?section=apikeys.

Bereich API-Schlüssel in den Kontoeinstellungen mit den Schaltflächen API-Dokumentation und Neuer Schlüssel

Hier werden Ihre Schlüssel aufgelistet. Solange Sie keinen erstellt haben, steht dort Momentan keine API-Schlüssel. Jeder Schlüssel hat nur Zugriff auf Ihr eigenes Konto.

Einen Schlüssel erstellen

Klicken Sie auf Neuer Schlüssel.
Geben Sie ihm einen aussagekräftigen Namen, etwa den des Skripts oder Tools, das ihn nutzen wird. Wenn dieses Skript wegfällt, wissen Sie, welchen Schlüssel Sie widerrufen müssen.
Bestätigen Sie das Erstellen des Schlüssels.
Der Kundenbereich zeigt den Schlüssel nur ein einziges Mal an. Kopieren Sie ihn sofort und bewahren Sie ihn sicher auf, zum Beispiel in einem Passwort-Manager. Er lässt sich später nicht mehr anzeigen.

Ein Schlüssel lässt sich außerdem auf bestimmte IP-Adressen beschränken, etwa auf die der Server, die ihn nutzen. Ohne Liste funktioniert er von jeder Adresse aus. Mit Liste wird ein Aufruf von einer anderen Adresse abgelehnt.

💡 Verlangt der Kundenbereich vor dem Erstellen eines Schlüssels die Zwei-Faktor-Authentifizierung, folgen Sie unserer Anleitung Zwei-Faktor-Authentifizierung (2FA) aktivieren und kehren Sie dann zu API-Schlüssel zurück.

Die API-Dokumentation lesen

Die Schaltfläche API-Dokumentation in diesem Bereich öffnet dash.ouiheberg.com/settings/api-docs.

Seite der API-Dokumentation mit Einführung, Authentifizierung, Fehlern und der Liste der Endpunkte nach Familie

Diese Dokumentation ist auf Ihr Konto zugeschnitten. Sie zeigt nur die Endpunkte, die für Sie freigeschaltet sind, sortiert nach Familie (Domains, Shop, Konto…). Jede Zeile nennt ihre Methode, GET zum Lesen, POST, PUT oder PATCH zum Senden oder Ändern, DEL zum Löschen. Oben zeigen Kennzeichen, wie viele Endpunkte für Sie offen sind und wie viele davon Ihr Konto ändern. Das Suchfeld oben links findet einen Endpunkt über ein Wort wie „Rechnung“ oder „Domain“.

Drei Punkte aus der Einführung sollten Sie sich merken.

Die Basisadresse der API lautet https://dash.ouiheberg.com/api/v1.
Alle Antworten kommen im JSON-Format. Senden Sie den Header Accept: application/json und zusätzlich Content-Type: application/json, wenn die Anfrage einen Body hat.
Oben auf der Seite führt Meine API-Schlüssel zu Ihren Schlüsseln zurück und Kundenbereich zum Kundenbereich.

Ein Endpunkt, den Sie brauchen, fehlt? Dann ist er für Ihr Konto nicht freigeschaltet. Schreiben Sie uns ein Ticket und beschreiben Sie, was Sie automatisieren möchten.

Einen ersten Aufruf senden

Jeder Aufruf trägt Ihren Schlüssel im Header Authorization, mit vorangestelltem Wort Bearer. Legen Sie den Schlüssel in einer Umgebungsvariablen ab, hier OH_API_KEY, statt ihn in Ihre Befehle zu schreiben. Ein Schlüssel, der in einem geteilten Skript oder in einem Ticket steht, muss widerrufen werden.

Hier der erste Aufruf, den die Dokumentation vorschlägt.

curl -H "Authorization: Bearer $OH_API_KEY" -H "Accept: application/json" https://dash.ouiheberg.com/api/v1/domains/check

Um die Parameter eines Endpunkts und seine Antwort zu sehen, klappen Sie ihn in der Dokumentation auf.

Auf der Seite ausprobieren

Mit der Dokumentation können Sie einen Aufruf auch ohne jede Installation senden. Fügen Sie einen Ihrer Schlüssel in die Seite ein. Er wird dort nicht gespeichert und verschwindet beim Neuladen. Starten Sie den Test dann im aufgeklappten Endpunkt.

Diese Tests sind echte Aufrufe. Ein Aufruf, der Ihr Konto ändert, ändert es endgültig, und die Seite fragt vor dem Senden nach einer Bestätigung. Ein Aufruf, der eine Bestellung aufgibt, erzeugt eine echte Rechnung, genau wie eine Bestellung im Shop.

In Postman importieren

Der Abschnitt In Postman importieren bietet eine fertige Sammlung zum Import, mit Ihren Endpunkten nach Familie sortiert. Die Datei enthält Ihren Schlüssel nicht. Sie tragen ihn in Postman in die dafür vorgesehene Variable ein.

Postman fragt nie nach einer Bestätigung. Ein Aufruf, der Ihr Konto ändert oder eine Bestellung aufgibt, geht sofort beim Senden raus.

Aufruflimits

Jeder Schlüssel hat ein eigenes Limit an Aufrufen pro Minute und pro Tag, das bei seiner Erstellung festgelegt wird. Jeder Aufruf zählt, auch Tests aus der Dokumentation. Der Abschnitt Aufruflimits der Dokumentation erklärt die Einzelheiten.

Darüber hinaus antwortet die API mit einem Fehler 429. Bauen Sie in Ihre Skripte eine Pause ein, statt den Aufruf in einer Schleife zu wiederholen. Das Minutenlimit ist nach einer Minute wieder frei, das Tageslimit am nächsten Tag.

Fehler verstehen

Ein abgelehnter Aufruf liefert einen HTTP-Statuscode und einen JSON-Body. Das Feld code nennt den genauen Grund und bleibt von Version zu Version gleich. Dieses Feld sollten Ihre Programme auswerten. Das Feld message richtet sich an Menschen.

Antwort	Bedeutung
`401`	Der Schlüssel fehlt, ist unbekannt, deaktiviert oder abgelaufen. Prüfen Sie, ob er vollständig kopiert wurde.
`403` `ip_not_allowed`	Der Schlüssel akzeptiert nur bestimmte IP-Adressen, und der Aufruf kam von einer anderen.
`403` `endpoint_not_granted`	Dieser Endpunkt ist für Ihr Konto nicht freigeschaltet. Schreiben Sie uns, um ihn zu erhalten.
`403` `route_not_allowed`	Der Endpunkt ist für Ihr Konto freigeschaltet, aber dieser Schlüssel deckt ihn nicht ab. Ändern Sie den Schlüssel oder nutzen Sie einen anderen.
`403` `api_access_blocked`	Der API-Zugang Ihres Kontos ist gesperrt. Schreiben Sie uns, um den Grund zu erfahren.
`429` `rate_limit_exceeded`	Das Minutenlimit des Schlüssels ist erreicht. Die Antwort nennt die Wartezeit.
`429` `daily_quota_exceeded`	Das Tageslimit des Schlüssels ist erreicht.

Einen Schlüssel widerrufen

Widerrufen Sie einen Schlüssel, sobald er nicht mehr gebraucht wird, oder beim kleinsten Zweifel, etwa wenn er in einem Ticket stand, in einem Skript geteilt wurde oder auf einem verlorenen Rechner lag.

Öffnen Sie Kontoeinstellungen › API-Schlüssel.
Klicken Sie in der Zeile des Schlüssels auf Widerrufen.

Programme, die diesen Schlüssel nutzten, erhalten nun einen Fehler 401. Sollen sie weiterlaufen, erstellen Sie einen neuen Schlüssel und ersetzen Sie den alten in ihrer Konfiguration.

💡 Sie sind Reseller? Die Schlüssel der Reseller-API werden nicht hier erstellt, sondern im Reseller-Bereich, den Sie über den Bereich Reseller-Konto öffnen.

Brauchen Sie Hilfe?

Um einen Endpunkt freischalten oder einen API-Zugang wiederherstellen zu lassen, eröffnen Sie ein Ticket über Tickets › Ticket öffnen (dash.ouiheberg.com/tickets/new) und beschreiben Sie, was Sie automatisieren möchten. Fügen Sie Ihren Schlüssel niemals in das Ticket ein.
Sie können uns auch auf unserem Discord schreiben.