Docs/ Referencia API/ Autenticación API

Autenticación API

Todos los endpoints REST viven bajo /api/v1. Los scripts, los trabajos de CI y las integraciones se autentican con una clave de API; el panel usa una sesión por cookie.

Claves de API

Una clave de API es la única credencial pensada para programas. Cree una por herramienta, así podrá revocar una integración sin tocar las demás:

En el panel, abra Configuración → Claves API y haga clic en Crear clave API.
Póngale un nombre que diga qué la usa, por ejemplo «Pipeline de CI».
Elija su nivel de acceso y, si lo desea, una fecha de caducidad.
Copie la clave de inmediato: solo se muestra una vez y se guarda cifrada con hash. Si la pierde, elimínela y cree otra.

Las claves empiezan por sh0_. Una clave nunca puede hacer más que la cuenta que la creó, y una clave no puede crear otras claves.

Niveles de acceso

Cada clave lleva uno de tres niveles de acceso, aplicado por el servidor en cada petición. A través de la API, el nivel es el campo scopes: read, deploy o admin.

Nivel	Puede	No puede
Solo lectura `read`	Consultar apps, despliegues, registros, métricas y la configuración, incluidas las variables de entorno, las credenciales de las bases de datos, las copias de seguridad y los archivos de los contenedores.	No puede modificar nada: ni desplegar, ni reiniciar, ni crear, ni eliminar. Sin terminal ni acceso al host.
Despliegue `deploy`	Todo lo que permite solo lectura, más desplegar, revertir, reiniciar, iniciar, detener y escalar las apps existentes, y subirles un nuevo archivo: la clave ejecuta el código que sube.	No puede crear ni eliminar apps, cambiar su configuración, dominios o variables de entorno, ni gestionar nodos, usuarios, claves o la configuración del servidor. Sin terminal.
Administración `admin`	Todo lo que puede hacer su cuenta, incluido crear y eliminar recursos, el terminal y el acceso al host.	Nunca más que su propio rol. No puede crear otras claves de API, ni gestionar las identidades de inicio de sesión o la obligación de doble autenticación.

Tip

Dé a cada herramienta el nivel más estrecho que funcione: un trabajo de CI que solo redespliega una app existente necesita Despliegue; un script de monitorización, Solo lectura.

Warning

Solo lectura sigue revelando secretos: puede leer variables de entorno y credenciales de bases de datos. Trate cada clave como una contraseña y nunca la suba a un repositorio.

Usar una clave

Envíe la clave en la cabecera Authorization: Bearer de cada petición:

Terminal

export SH0_TOKEN="sh0_..."
curl https://panel.example.com/api/v1/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Warning

La cabecera X-API-Key no se lee. Una petición que solo la lleva se trata como anónima y recibe un 401 «No authentication token provided».

Sesiones del panel

El panel inicia sesión con POST /api/v1/auth/login. Si tiene éxito, el servidor establece cookies HttpOnly (sh0_access y sh0_refresh) y devuelve un csrf_token en el cuerpo de la respuesta; no se devuelve ningún token en el cuerpo. Este flujo está pensado para navegadores: para scripts, use una clave de API.

La sesión de acceso dura 24 horas. El panel la renueva mediante POST /api/v1/auth/refresh, que también emite una nueva sesión de renovación de 30 días; una sesión sin usar durante 30 días termina.

Cambiar la contraseña cierra todas las demás sesiones. Los intentos de inicio de sesión están limitados a 5 fallos cada 15 minutos; una contraseña correcta no cuenta para el límite.

Inicio de sesión con dos factores

Cuando la cuenta tiene autenticación de dos factores, el inicio de sesión responde requires_totp con un totp_nonce de corta duración en lugar de abrir la sesión. Después, el cliente envía el nonce y el código de 6 dígitos (o un código de respaldo) a POST /api/v1/auth/totp/verify. La verificación está limitada a 5 intentos cada 5 minutos.

Protección CSRF

Las peticiones autenticadas por la cookie de sesión deben repetir el token CSRF en la cabecera X-CSRF-Token en cada llamada que modifique estado. Las peticiones autenticadas con una clave de API en la cabecera Authorization no lo necesitan.

Errores de autenticación

Los errores usan el sobre de error estándar. Por ejemplo, una clave desconocida o revocada:

401 Unauthorized

{"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}

HTTP	Code	Significado
401	`UNAUTHORIZED`	Sin credencial, clave desconocida, caducada o revocada, sesión caducada, o correo o contraseña incorrectos al iniciar sesión
403	`FORBIDDEN`	Autenticado, pero el nivel de acceso de la clave o el rol de la cuenta no permite esta acción
429	`RATE_LIMITED`	Demasiados intentos: 5 inicios de sesión fallidos cada 15 minutos, o 5 verificaciones de dos factores cada 5 minutos

Referencia de comandos

Inicio rápido