Panel API

Automatisieren Sie Herne aus Skripten, CI-Pipelines und Agenten mit berechtigungsbasierten Bearer-Tokens — dieselben Regeln und Limits wie im Panel selbst.

Was die Panel-API ist

Die Panel-API stellt CI-Pipelines, Kommandozeilenwerkzeugen, Betriebsskripten, KI-Agenten und Integrationen dieselben Funktionen wie das Browser-Panel bereit. Sie nutzt dieselbe Verarbeitungsschicht. Ein Token kann nie mehr als sein Eigentümer im Panel. Mandantengrenzen, Paketlimits, Rollenprüfungen und Richtlinien gelten gleichermaßen.

Die API lebt unter /panel/api als zustandslose Träger-Token-Oberfläche (keine Sitzung, keine CSRF). Es ist eine Management-API für vertrauenswürdige Betreiber dieser Installation, keine Public-Hosting-API: Es gibt keine anonyme Anmeldung und keine Ausgabe von Self-Service-Token.

Ein Token erstellen

Tokens werden nur aus der Panel-Benutzeroberfläche erstellt - es gibt keinen handwerklichen Befehl und keinen API-Endpunkt für die Token-Verwaltung.

  1. Gehe zu Panel → API-Tokens.
  2. Geben Sie einen Namen ein (z. B. ci-deploy) und kreuzen Sie die Fähigkeiten an, die der Anrufer benötigt. Jede Gruppe hat einen Alles auswählen Umschalter, und einer über der Liste wählt jede Fähigkeit auf einmal aus.
  3. Klicken Sie auf Token erstellen. Das Plain-Token (hrn_ gefolgt von 64 zufälligen Zeichen) wird angezeigt Genau einmal - kopieren Sie es sofort. Nur sein SHA-256 Hash wird gespeichert.

Der Bildschirm übergibt Ihnen beide Client-Schlüssel zusammen, bereit, in die .env Datei Ihres Anrufers oder den CI-Geheimspeicher einzufügen:

HERNE_API_URL=https://your-server.example/panel/api
HERNE_API_TOKEN=hrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ein verlorenes Token lässt sich weder wiederherstellen noch erneut anzeigen. Widerrufen Sie es und erstellen Sie ein neues. Beim Bearbeiten ändern sich nur Name und Berechtigungen. Der geheime Tokenwert wird dabei nicht erneuert.

Berechtigungsgruppen

Berechtigungen sind nicht hierarchisch verschachtelte resource.verb-Zeichenfolgen mit Punkten als Trennzeichen. Sie sind nach Berechtigungsumfang gruppiert:

  • Standard — Leseflächen plus alltägliche Automatisierung (sites.read, deploy.run, backups.read, me.read, ...).
  • Fortgeschritten — opt-in schreibt (sites.write, databases.write, env.read/env.write, artisan.run, ...). env.readist absichtlich write-tier: site .env Dateien enthalten Anmeldeinformationen.
  • Zerstörerisch — Löschen und Shell-Zugriff sind bewusst getrennt (sites.delete, databases.delete, shell.run, …). Lesevorgänge ändern keine Daten, Schreibrechte schließen keine Löschrechte ein, und Löschvorgänge werden nicht kaskadiert.
  • Administrator — admin-role-gated Oberflächen (admin.users.read, admin.firewall.read, ...). Nur Admins können diese gewähren, und der Eigentümer muss die Admin-Rolle zum Zeitpunkt der Anfrage noch innehaben.

Ein Token verwenden

Senden Sie das Token im Authorization-Header – nur Bearer, kein Abfrage-Parameter oder Cookie-Fallback:

GET /panel/api HTTP/1.1
Host: your-server.example
Accept: application/json
Authorization: Bearer hrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Oder mit Curl:

curl -H "Authorization: Bearer $HERNE_API_TOKEN" $HERNE_API_URL/me

GET /panel/api ist der Discovery-Endpunkt: Ohne ein Token gibt es Public-Safe-Bootstrap JSON zurück; mit einem Token verbindet es auch die Ressourcen, die Ihre Fähigkeiten erreichen können.

Antworten

Erfolgsantworten sind ok-erste flache JSON mit Domänenschlüsseln auf der obersten Ebene:

{"ok": true, "site": {"slug": "example-com", "domain": "example.com"}}

Fehler teilen sich die Form, fügen eine stabile Maschine hinzu code und tragen immer Links zur Selbstfindung:

{
  "ok": false,
  "code": "missing_capability",
  "message": "This token does not have the sites.write capability.",
  "api_discovery_url": "/panel/api",
  "openapi_url": "/panel/api/openapi.json"
}

Statusnutzung: 200 Lese-/Updates, 201 Create, 401 fehlende/ungültige/entzogene Token, 403 fehlende Fähigkeiten oder ausfallende Richtlinien, 404 unbekannte oder ausländische Ressourcen, 422 Validierung, 429 Rate limitiert. Validierungsfehlerliste errors[] als {path, message} Objekte.

Anfragelimits

Die API erlaubt 120 Anfragen pro Minute je ip|token. Für aufwendige Endpunkte gelten zusätzlich strengere Panel-Limits pro Route: pro Minute 10 Deployments, 5 Wiederherstellungen, 20 Artisan-Anfragen, 60 Shell-Anfragen und 5 Panel-Updates.

Sicherheitshinweise

  • Das Token im Klartext wird einmal bei der Erstellung angezeigt und nie gespeichert. Gespeichert wird nur der SHA-256-Hash.
  • Das Widerrufen eines Tokens lehnt seine Anfragen sofort ab; die Zeile wird für das Auditing aufbewahrt. Löschen entfernt die Zeile und ihre Aktivitätshistorie.
  • Die Admin-Fähigkeiten werden zum Zeitpunkt der Anfrage erneut überprüft: Eine Rolle, die nach der Token-Ausgabe widerrufen wurde, deaktiviert sie sofort.
  • shell.run ist in keinem Standardsatz enthalten. Die Berechtigung muss ausdrücklich ausgewählt werden und nutzt dieselbe isolierte Shell pro Website wie das Panel-Terminal.
  • Die letzte Aktivität jedes Tokens ist mit Methode, Pfad, Berechtigungsergebnis und IP-Adresse unter API-Tokens sichtbar. Anfrageinhalte und geheime Tokenwerte werden nie protokolliert.

Funktionsumfang

Jede Aktion, die das Panel anbietet, hat einen API-Endpunkt, einschließlich Domain-Aliasen und der externen Umleitung, der Laravel-Runtime-Konvertierung, der Aktualisierung der Festplattennutzung, der Protokollabkürzung, der Exportdateien pro Datenbank, der Schätzungen der Backup-Größe, des Browsens in der Datenbank, der Rechnungen, der Hilfethemen und Ihres eigenen Profils. Drei Dinge bleiben durch das Design Panel-only: API-Token-Management selbst, Webmail und der Authentifizierungsfluss (Login, Registrierung, Passwort-Reset, E-Mail-Verifizierung). Der Setup-Assistent hat keinen eigenen Endpunkt - jeder seiner Schritte ist eine separate API-Primitive.

OpenAPI

Ein laufzeitgeneriertes OpenAPI 3.1-Dokument ist unter GET /panel/api/openapi.json verfügbar (Token erforderlich). Richten Sie Ihren Client-Generator oder Ihr Agenten-Tooling auf die vollständige Endpunkt- und Schemaoberfläche.