Panel API

Automatice Herne desde scripts, pipelines de CI y agentes con tokens bearer de capacidades limitadas — las mismas reglas y límites que el propio panel.

Qué es la API del panel

La API del panel ofrece a las canalizaciones de CI, herramientas de línea de comandos, scripts de operación, agentes de IA e integraciones las mismas funciones que el panel web. Usa la misma capa de operaciones. Un token nunca concede más permisos de los que tiene su propietario en el panel. Se aplican los mismos límites de inquilino, cuotas del plan, controles de roles y políticas.

La API vive bajo /panel/api como una superficie apátrida de token de portador (sin sesión, sin CSRF). Es una API de gestión para operadores de confianza de esta instalación, no un API de hosting público: no hay registro anónimo y no hay emisión de token de autoservicio.

Crear un token

Las fichas se crean desde el panel UI solamente — no hay un comando artesano y ningún punto final de API para la gestión de fichas.

  1. Vaya a Panel → Tokens de API.
  2. Introduzca un nombre (por ejemplo ci-deploy) y haga clic en las capacidades que necesita el llamante. Cada grupo tiene un Seleccione todorebosante, y uno encima de la lista selecciona cada capacidad a la vez.
  3. Haga clic en Crear Token. El token (hrn_seguido de 64 caracteres aleatorios) se muestra exactamente una vez — copiarlo inmediatamente. Sólo se almacena su hash SHA-256.

La pantalla te da las teclas de ambos clientes juntos, listo para pegar en el archivo .env de tu callador o la tienda secreta de CI:

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

Un token perdido no se puede recuperar ni volver a mostrar. Revócalo y crea uno nuevo. La edición solo cambia el nombre y los permisos. El valor secreto del token se mantiene.

Grupos de permisos

Las capacidades son cuerdas planas punteadas resource.verb, agrupadas por el poder:

  • Predeterminado — leer superficies más automatización cotidiana (sites.read, deploy.run, backups.read, me.read, ...).
  • Avances — el opt-in escribe (sites.write, databases.write, env.read/env.write, artisan.run, ...). env.read es deliberadamente mástil: los archivos .env del sitio contienen credenciales.
  • Destructivo — el acceso a la consola y las eliminaciones se separan expresamente (sites.delete, databases.delete, shell.run, …). Una lectura no modifica datos, los permisos de escritura no incluyen el de eliminar y las eliminaciones no se propagan en cascada.
  • Administrador — superficies desgarradas por el administrador (admin.users.read, admin.firewall.read, ...). Sólo los administradores pueden conceder estos, y el propietario debe mantener el papel de administrador a la hora de solicitud.

Usar un token

Envíe el token en el encabezado Authorization — sólo portador, sin parámetros de consulta o descomposición de cookies:

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

O con el curl:

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

GET /panel/api es el punto final del descubrimiento: sin un token devuelve el bootstrap público-safe JSON; con un token que también vincula los recursos que sus capacidades pueden alcanzar.

Respuestas

Las respuestas de éxito son ok-primer plano JSON con claves de dominio en el nivel superior:

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

Los errores comparten la forma, añaden una máquina estable code, y siempre llevan enlaces de autodescubrimiento:

{
  "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"
}

Uso del estado: 200 lectura/actualización, 201 crear, 401 ficha faltante/inválido/revocado, 403 capacidad de falta o política de fallo, 404 recurso desconocido o extranjero, 422 validación, 429 tasa limitada. Lista de errores de validación errors[] como {path, message} objetos.

Límites de solicitudes

La API admite 120 solicitudes por minuto por ip|token. Los endpoints más costosos también aplican los límites más estrictos del panel por ruta: por minuto, 10 despliegues, 5 restauraciones, 20 solicitudes de Artisan, 60 de consola y 5 actualizaciones del panel.

Notas de seguridad

  • El token en texto claro se muestra una vez al crearlo y nunca se almacena. Solo se conserva el hash SHA-256.
  • Revocar una ficha rechaza inmediatamente sus solicitudes; la fila se mantiene para la auditoría. Eliminar elimina la fila y su historia de actividad.
  • Las capacidades de los administradores se revisan nuevamente a la hora de la solicitud: un papel revocado después de la emisión de token los desactiva inmediatamente.
  • shell.run no forma parte de ningún conjunto predeterminado. Asegúrate de seleccionarlo expresamente. Usa el mismo entorno de consola aislado por sitio que el terminal del panel.
  • La pantalla de tokens de API muestra la última actividad de cada token con el método, la ruta, el resultado de autorización y la IP. Los cuerpos de las solicitudes y los valores secretos de los tokens nunca se registran.

Cobertura

Cada acción que el panel ofrece tiene un punto final de API, incluyendo alias de dominio y la redireccion externa, la conversión de tiempo de ejecución Laravel, actualización de uso de disco, truncación de registros, archivos de exportación de base de datos, estimaciones de tamaño de copia de seguridad, navegación por bases de datos, facturas, los temas de ayuda, y su propio perfil. Tres cosas permanecen solos por diseño: API token management itself, webmail y el flujo de autenticación (login, registro, reset de contraseña, verificación de correo electrónico). El asistente de configuración no tiene un punto final propio — cada uno de sus pasos es un API primitivo separado.

OpenAPI

Un documento de OpenAPI 3.1 generado por tiempo de ejecución está disponible en GET /panel/api/openapi.json (token required). Indique su generador o agente de herramientas en él para el punto final completo y la superficie del esquema.