Restricciones de claves API

Limita una clave API exactamente a lo que necesita: un conjunto de alcances, una lista de IPs permitidas y una caducidad.

Alcances

Una clave puede limitarse a un subconjunto de alcances. Una petición con una clave sin el alcance requerido devuelve 403. Una clave creada sin alcances tiene acceso completo. Los tokens de sesión (el panel) siempre tienen acceso completo.

Alcance	Permite
`servers:read`	Listar/obtener servidores, recursos
`servers:write`	Desplegar, redimensionar, eliminar
`servers:power`	Señales de energía, comandos, consola
`files:read`	Listar, leer, descargar archivos
`files:write`	Escribir, eliminar archivos
`billing:read`	Saldo, transacciones, facturas, presupuesto
`billing:write`	Checkout, cambiar presupuesto
`keys:write`	Crear / revocar claves API

Lista de IPs permitidas

Restringe una clave a IPs específicas. Las entradas pueden ser IPs exactas o prefijos (p.ej. 10.0.0. coincide con una subred). Una petición desde otra dirección devuelve 403. Deja vacío para permitir cualquier IP.

Caducidad

Establece expiresInDays para que una clave deje de funcionar después de un plazo — ideal para tokens de CI o integraciones temporales. Las claves caducadas devuelven 401.

Crear una clave restringida

bash
POST /v1/keys
{
  "name": "ci-deploy",
  "scopes": ["servers:read", "servers:write"],
  "allowedIps": ["203.0.113.4"],
  "expiresInDays": 90
}
→ { "id": "...", "secret": "ak_live_...", "message": "Guarda este secreto ahora." }

El secreto se devuelve una vez. Lista las claves (con sus restricciones) en GET /v1/keys.

Consulta Autenticación para ver cómo se verifican las claves en cada petición.