API de Plak

Alcance por usuario, estado de implementación y convenciones de la API de sitios y servidores de Plak.

La API para usuarios de Plak está destinada a trabajar con los sitios y servidores asociados a su propia cuenta, dentro de sus permisos. La gestión de usuarios y paquetes queda fuera del acceso con claves personales y de esta referencia pública de endpoints.

Alcance del acceso personal

Estas restricciones deben aplicarse en el backend, tanto a listados como a consultas por identificador y a cualquier operación futura. La paginación y sus totales también deben calcularse sobre los recursos del usuario. Conocer el identificador de un recurso ajeno no debe permitir consultarlo ni modificarlo.

La identidad se obtiene de la API key. El cliente no puede elegir otro usuario mediante user_id. Un endpoint de identidad como el /api/v1/me propuesto devolvería únicamente la propia cuenta, sin habilitar la administración de usuarios.

La retirada de endpoints de esta documentación no cambia los permisos del código existente. El aislamiento y el rechazo de claves personales en las operaciones administrativas son requisitos pendientes de implementación.

Entornos y comprobación HTTP

En desarrollo, GET /api/sites con Accept: application/json respondió 302 hacia el inicio de sesión de Cloudflare Access. La raíz del sitio también respondió 302. No se alcanzó una respuesta autenticada de Laravel ni se utilizaron credenciales.

Cloudflare Access es una capa anterior a la API. Su redirección no demuestra que la API esté deshabilitada ni que una API key sea incorrecta. Para probar el futuro CLI en este entorno habrá que resolver también el acceso autorizado a esa capa; la clave personal de Plak no la sustituye.

Autenticación administrativa existente

Todas las rutas de routes/api.php reciben el prefijo /api y los middleware api y global.api.authenticated desde app/Providers/RouteServiceProvider.php.

El middleware GlobalApiAuthenticated comprueba:

1. Que el ajuste enable_api esté activo y exista api_token.
2. Que el Bearer token coincida con el valor descifrado de api_token.

El administrador gestiona estos ajustes desde la página de configuración de Filament, implementada en app/Filament/Pages/Settings.php. El token se almacena cifrado de forma reversible. El botón de generación utiliza una cadena aleatoria de 20 caracteres.

Cabeceras para consumir la API actual:

Authorization: Bearer <TOKEN_GLOBAL>
Accept: application/json
Content-Type: application/json

Content-Type corresponde a peticiones con cuerpo JSON. Los ejemplos de esta documentación utilizan datos ficticios.

La clave global concede acceso administrativo a estos endpoints. No tiene un usuario propietario, permisos por token, caducidad por dispositivo ni revocación individual. Cambiarla afecta a los clientes que la utilizan. No es la credencial apropiada para distribuir entre usuarios del CLI.

El guard api declarado en config/auth.php no es el mecanismo usado por estas rutas. Tampoco deben confundirse el token global de Plak y la credencial que el backend utiliza para llamar a Ploi.

Operaciones de sitios y servidores existentes

La siguiente tabla describe el código administrativo revisado, no un acceso personal ya disponible:

Consulta sus parámetros, respuestas y estado de adaptación en la referencia de sitios y servidores.

Respuestas y paginación

En los endpoints administrativos de sitios y servidores, las consultas individuales y creaciones devuelven un objeto bajo data. El listado de sitios devuelve:

{
  "data": [],
  "links": {
    "first": "https://panel.plak.work/api/sites?page=1",
    "last": "https://panel.plak.work/api/sites?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "links": [],
    "path": "https://panel.plak.work/api/sites",
    "per_page": 15,
    "to": null,
    "total": 0
  }
}

El ejemplo ilustra la estructura; meta.links contiene los enlaces de navegación generados por Laravel. Se avanza mediante ?page=2 o links.next. Los controladores usan paginate() sin tamaño explícito, y las pruebas esperan 15 elementos por página. No hay un parámetro per_page implementado en esos controladores.

Estados HTTP

El middleware global utiliza 403, no 401, para las credenciales incorrectas. La tabla describe Laravel; un proxy como Cloudflare Access puede responder antes, como ocurrió con el 302 observado en desarrollo.

El grupo api en app/Http/Kernel.php aplica throttle:60,1: 60 peticiones por minuto. Con estas llamadas sin identidad de usuario, el middleware estándar agrupa por dominio/IP, sujeto a la configuración de proxies. No hay una cuota por API key personal. El limitador nombrado api del proveedor de rutas no es el que referencia ese grupo.

Lo que todavía no existe

• Endpoint de identidad /api/me o /api/v1/me.
• Emisión, listado o revocación de tokens personales.
• Filtrado automático de sitios por el usuario de la credencial.
• Listado, consulta, actualización o eliminación de servidores en esta API.
• Catálogo API de proveedores, planes o regiones para preparar una creación de servidor.
• Endpoints API para las funciones web de WordPress, DNS, bases de datos, SSH o certificados.
• Flujo de autorización de dispositivo o intercambio navegador–CLI.

Las rutas web de esas funciones usan sesión y respuestas de interfaz; no constituyen una API pública Bearer equivalente.

Fuentes y alcance

Archivos del repositorio del panel consultados:

• routes/api.php y app/Providers/RouteServiceProvider.php.
• app/Http/Kernel.php, app/Http/Middleware/GlobalApiAuthenticated.php y app/Exceptions/Handler.php.
• app/Http/Controllers/Api/ y app/DataTransferObjects/.
• tests/Feature/Http/Controllers/Api/ y tests/Feature/Http/Middleware/GlobalApiAuthenticatedTest.php.

Se leyeron las pruebas, pero no se ejecutaron ni se realizaron operaciones de escritura contra el panel. Para el flujo futuro, consulta conexión del CLI con el panel.