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.

  1. Vai a Pannello → API Tokens.
  2. 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.
  3. 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 .env contengono 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.run non 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.