Pannello API
Automatizza Herne dagli script, dalle condutture CI e dagli agenti con token di portatore azionati da capacità, le stesse regole e i limiti del pannello stesso.
Che cosa è il pannello API
Il pannello API espone le stesse funzionalità del pannello browser alle macchine: CI pipelines, CLI tooling, script operatore, AI agenti e integrazioni di terze parti. Si tratta di un secondo trasporto sullo stesso strato di orchestrazione — un token non garantisce mai più che il suo utente proprietario può fare nel pannello, e inquilino scoping, limiti di piano, controlli di ruolo e politiche si applicano identicamente.
API vive sotto /panel/api come superficie senza condizioni (senza sessione, nessun CSRF). È una gestione API per operatori di fiducia di questa installazione, non un hosting pubblico API: non c'è alcuna registrazione anonima e nessun rilascio self-service token.
Creare un Token
I gettoni sono creati solo dal pannello UI: non esiste artisan command e nessun endpoint API per la gestione dei token.
- Vai a Pannello → API Tokens.
- Inserisci un nome (ad esempio
ci-deploy) e seleziona le funzionalità di cui il chiamante ha bisogno. Ogni gruppo ha una funzione Seleziona tutto, e uno sopra l'elenco seleziona ogni funzionalità in una sola volta. - Fare clic su Creare Token. Il token normale (
hrn_seguito da 64 caratteri casuali) è mostrato esattamente una volta — copiarlo immediatamente. Solo il suo SHA-256 hash è memorizzato.
Lo schermo ti mette insieme entrambi i tasti del cliente, pronti a incollare nel file .env del chiamante o nel negozio segreto CI:
HERNE_API_URL=https://your-server.example/panel/api
HERNE_API_TOKEN=hrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Un token perso non può essere recuperato o ri-proposto. Rivolgilo e creane uno nuovo invece. Modificare un token cambia solo nome e capacità — non c'è rotazione segreta.
Gruppi di responsabilità
Le capacità sono stringhe resource.verb piane, raggruppate per potenza:
- Predefinito — superfici di lettura più automazione quotidiana (
sites.read,deploy.run,backups.read,me.read, ...). - Avanzato — scrive opt-in (
sites.write,databases.write,env.read/env.write,artisan.run, ...).env.readè volutamente scrittura-tier: i file del sito.envcontengono le credenziali. - Destructive — cancella e accede alla shell, deliberatamente separato (
sites.delete,databases.delete,shell.run, ...). Reads never mutate, writes never implica deletes, and no delete cascades. - Amministrazioni — superfici arrotolate (
admin.users.read,admin.firewall.read, ...). Solo gli amministratori possono concedere queste, e il proprietario deve ancora tenere il ruolo di amministratore al momento della richiesta.
Utilizzo di un Token
Invia il token nell'intestazione Authorization — solo il portatore, nessun parametro di query o cookie fallback:
GET /panel/api HTTP/1.1
Host: your-server.example
Accept: application/json
Authorization: Bearer hrn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
O con curl:
curl -H "Authorization: Bearer $HERNE_API_TOKEN" $HERNE_API_URL/me
GET /panel/api è il punto finale della scoperta: senza un gettone restituisce la formazione di stivali pubblici sicuri JSON; con un token esso collega anche le risorse che le vostre capacità possono raggiungere.
Risposte
Le risposte di successo sono ok-first flat JSON con i tasti di dominio al livello superiore:
{"ok": true, "site": {"slug": "example-com", "domain": "example.com"}}
Gli errori condividono la forma, aggiungono una macchina stabile code, e portano sempre i link di auto-scoprimento:
{
"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"
}
Codici di stato: 200 per lettura o aggiornamento, 201 per creazione, 401 per token assente, non valido o revocato, 403 per permesso mancante o regola di autorizzazione non soddisfatta, 404 per risorsa sconosciuta o appartenente a un altro account, 422 per validazione, 429 per limite di richieste raggiunto. Gli errori di validazione riportano errors[] come oggetti {path, message}.
Limiti di tasso
API consente di effettuare richieste 120 al minuto, con la chiave ip|token. Gli endpoint più economici portano i tredici per-route del pannello in alto (deploy 10/min, ripristina 5/min, artisan 20/min, shell 60/min, aggiornamenti del pannello 5/min).
Note di sicurezza
- Il token normale viene mostrato una volta alla creazione e mai memorizzato — solo l'hash SHA-256 persiste.
- Revocare un token blocca subito le sue richieste e conserva la riga per l’audit. Eliminarlo rimuove la riga e la cronologia delle attività.
- Le capacità di amministrazione vengono ricontrollate al momento della richiesta: un ruolo revocato dopo l'emissione di token li disabilita immediatamente.
shell.runnon fa mai parte di nessun set predefinito — deve essere selezionato deliberatamente e scorre attraverso lo stesso limite isolato per-sito shell del terminale del pannello.- Ogni token registra la sua ultima attività (metodo, percorso, permesso/denied, IP) — visibile sullo schermo dei Token API. I corpi di richiesta e il materiale di token non sono mai registrati.
Copertura
Ogni azione che il pannello offre ha un endpoint API, tra cui alias di dominio e reindirizzamento esterno, la conversione runtime Laravel, aggiornamento di disco-usage, troncamento di log, dump per-database, stime di dimensione di backup, navigazione del database, fatture, argomenti di aiuto e il proprio profilo. Tre cose rimangono solo pannello per design: API gestione token, webmail e il flusso di autenticazione (login, registrazione, reset password, verifica email). La procedura guidata di configurazione non ha un punto finale proprio — ciascuno dei suoi passaggi è un primitivo API separato.
Aprire l'API
È disponibile un documento OpenAPI 3.1 generato a tempo di esecuzione presso GET /panel/api/openapi.json (previa richiesta). Puntare il generatore del cliente o l'agente che lo attrezzo per la superficie di endpoint e schema completo.