Panneau API
Automatisez Herne à partir de scripts, de pipelines CI et d'agents avec des jetons porteurs de champ d'action – les mêmes règles et limites que le panneau lui-même.
Ce que le panneau API est
Le panneau API expose les mêmes capacités que le panneau de navigateur aux appelants de machine : pipelines CI, outillage CLI, scripts opérateurs, agents AI et intégrations tierces. C'est un second transport sur la même couche d'orchestration — un jeton ne donne jamais plus que son propre utilisateur peut faire dans le panneau, et la délimitation des locataires, les limites de plan, les contrôles de rôles, et les politiques s'appliquent de façon identique.
Le API vit sous /panel/api comme une surface de jeton au porteur apatride (pas de session, pas de CSRF). C'est un API de gestion pour les opérateurs fiables de cette installation, pas un hébergement public API : il n'y a pas d'inscription anonyme et aucun jeton en libre-service.
Création d'un jeton
Les jetons sont créés à partir du panneau UI seulement — il n'y a pas de artisan command et aucun point d'arrêt API pour la gestion des jetons.
- Allez sur Panneau → Jetons API.
- Saisissez un nom (par exemple
ci-deploy) et cochez les fonctionnalités dont l'appelant a besoin. Chaque groupe a un basculement Tout sélectionner, et un au-dessus de la liste sélectionne chaque capacité à la fois. - Cliquez sur Créer un jeton. Le jeton simple (
hrn_suivi de 64 caractères aléatoires) est montré exactement une fois — copiez-le immédiatement. Seul son hachage SHA-256 est stocké.
L'écran vous met les deux clés clientes ensemble, prêtes à coller dans le fichier .env de votre appelant ou le magasin secret CI:
HERNE_API_URL=https://your-server.example/panel/api
HERNE_API_TOKEN=hrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Un jeton perdu ne peut pas être récupéré ou re-displayé. Revoquez-le et créez-en un nouveau. Modifier un jeton change son nom et ses capacités seulement — il n'y a pas de rotation secrète.
Groupes de capacités
Les capacités sont des chaînes resource.verb pointillées plates, regroupées par puissance :
- Par défaut — surfaces de lecture plus l'automatisation quotidienne (
sites.read,deploy.run,backups.read,me.read, ...). - Avancé — opt-in écrit (
sites.write,databases.write,env.read/env.write,artisan.run, ...).env.readest délibérément écrit-tier: les fichiers du site.envcontiennent des identifiants. - Déstructif — supprime et shell access, délibérément séparé (
sites.delete,databases.delete,shell.run, ...). lit jamais muter, n'écrit jamais impliquer des suppressions, et aucune suppression cascades. - Administrateur — Surfaces managées (
admin.users.read,admin.firewall.read, ...).Seuls les administrateurs peuvent les accorder, et le propriétaire doit toujours occuper le rôle d'administrateur au moment de la demande.
Utilisation d'un jeton
Envoyer le jeton dans l'en-tête Authorization — porteur seulement, aucun paramètre de requête ou de retour de cookie:
GET /panel/api HTTP/1.1
Host: your-server.example
Accept: application/json
Authorization: Bearer hrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Ou avec boucle:
curl -H "Authorization: Bearer $HERNE_API_TOKEN" $HERNE_API_URL/me
GET /panel/api est le point de départ de la découverte : sans jeton, il retourne le bootstrap public-safe JSON ; avec un jeton, il relie également les ressources que vos capacités peuvent atteindre.
Réponses
Les réponses à la réussite sont ok-premier plat JSON avec les clés de domaine au niveau supérieur:
{"ok": true, "site": {"slug": "example-com", "domain": "example.com"}}
Les erreurs partagent la forme, ajoutent une machine stable code, et portent toujours des liens d'auto-découverte:
{
"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"
}
Codes d’état : 200 pour la lecture ou la mise à jour, 201 pour la création, 401 si le jeton est absent, invalide ou révoqué, 403 si une capacité manque ou si une règle d’autorisation échoue, 404 si la ressource est inconnue ou appartient à un autre compte, 422 pour la validation, 429 si la limite de requêtes est atteinte. Les erreurs de validation présentent errors[] sous forme d’objets {path, message}.
Limites de taux
Le API permet de sélectionner les requêtes 120 par minute sur le ip|token. Les paramètres d'évaluation coûteux portent les gaz par route les plus serrés du panneau sur le dessus (déploiement 10/min, restauration 5/min, artisan 20/min, shell 60/min, mise à jour du panneau 5/min).
Notes de sécurité
- Le jeton simple est montré une fois à la création et jamais stocké — seul le hachage SHA-256 persiste.
- La révocation d’un jeton bloque immédiatement ses requêtes et conserve sa ligne pour l’audit. La suppression retire sa ligne et son historique d’activité.
- Les capacités d'admin sont revérifiées au moment de la demande : un rôle révoqué après la délivrance de jeton les désactive immédiatement.
shell.runne fait jamais partie d'un ensemble par défaut — il doit être sélectionné délibérément et passe à travers la même limite isolée de shell par site que le terminal du panneau.- Chaque jeton enregistre sa dernière activité (méthode, chemin, permis/défaut, IP) – visible sur l'écran des jetons API. Demander des corps et du matériel de jeton ne sont jamais enregistrés.
Couverture
Chaque action proposée par le panneau comporte un paramètre API, incluant des alias de domaine et la redirection externe, la conversion d'exécution Laravel, le rafraîchissement de l'utilisation du disque, la troncation de log, les décharges par base de données, les estimations de taille de sauvegarde, la navigation dans la base de données, les factures, les sujets d'aide et votre profil. Trois choses restent panneau-seulement par conception: API jeton gestion elle-même, webmail, et le flux d'authentification (login, enregistrement, réinitialisation du mot de passe, vérification de l'e-mail). L'assistant de configuration n'a pas de point d'arrivée propre — chacune de ses étapes est un primitive API séparé.
OpenAPI
Un document OpenAPI 3.1 généré par l'exécution est disponible à GET /panel/api/openapi.json (jeton requis). Pointez votre générateur de client ou outil d'agent à lui pour la surface complète du point de départ et du schéma.