Guía rápida de la API

Las claves de API permiten que sus propios scripts y su CI actúen en nombre de su organización. Cada clave lleva solo los alcances que usted le asigna.

Crear una clave

1. Active la autenticación de dos factores en Settings. Es obligatoria para crear una clave.
2. En la consola, abra Keys y elija Create key.
3. Nombre la clave según lo que la usa, por ejemplo ci-runner.
4. Elija sus alcances y su vigencia: 30, 90, 180 o 365 días.
5. Opcionalmente, defina sus límites de gasto (ver más abajo).
6. Copie la clave. Se muestra una sola vez.

Los propietarios y administradores de la organización gestionan las claves. Cada clave nueva se notifica por correo electrónico a la persona que la creó.

Autenticarse

Envíe la clave como token Bearer:

export NODELODGE_API_KEY="nl_live_..."
curl https://nodelodge.com/v1/whoami \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

La respuesta indica la organización y los alcances que lleva la clave:

{
  "orgId": "6f1c...",
  "via": "api_key",
  "apiKeyId": "2b9e...",
  "scopes": ["workloads:read"]
}

Use whoami en un pipeline para fallar de inmediato ante una clave revocada, caducada o mal escrita.

Referencia

Cada endpoint, con sus parámetros y un ejemplo curl, está en la referencia de la API. La misma descripción se publica como documento OpenAPI 3.1 en https://nodelodge.com/v1/openapi.json: impórtelo en su cliente HTTP o genere con él un cliente tipado.

curl https://nodelodge.com/v1/openapi.json -o nodelodge-openapi.json

Alcances

Asigne a cada clave el mínimo de alcances que su tarea necesita. Una clave que solo informa del estado necesita workloads:read.

Qué puede llamar una clave

Una clave aumenta el presupuesto y lee los datos de conexión solo de las sesiones que lanzó. Cualquier clave de la organización con workloads:write puede detener una sesión.

Lanzar una sesión

curl -X POST https://nodelodge.com/v1/sessions \
  -H "Authorization: Bearer $NODELODGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"partnerOfferId":"3f0c8f5e-8c3a-4f39-9a8e-2d9b4c1e7a10","environmentId":"jupyterlab","pricing":"on_demand","budgetCents":2000,"allowedCidr":"203.0.113.7","sshPublicKey":"ssh-ed25519 AAAA... you@laptop"}'

• budgetCents es lo máximo que puede costar la sesión. Se reserva sobre su crédito al lanzar. La facturación sigue el tiempo real en que la máquina está en marcha, desde que está lista, y Budget Guard detiene la sesión antes de que se gaste el presupuesto.
• allowedCidr es la dirección IPv4 pública, o un rango de hasta /24, autorizada a conectarse por SSH.
• sshPublicKey abre solo esta sesión: la clave no se guarda en su cuenta. Para usar una clave guardada en la consola, envíe en su lugar su ID en sshKeyIds. Guardar o eliminar una clave de su cuenta se hace en la consola.
• environmentId: las máquinas de centro de datos ejecutan jupyterlab. GET /v1/environments?offerId=... lista lo que puede ejecutar una máquina Community.
• Añada maxDurationHours para detener la sesión tras ese número de horas, aunque quede presupuesto.
• La cabecera Idempotency-Key hace que una solicitud reintentada inicie una sola sesión.

Lea la sesión con GET /v1/sessions/{id}: cuando su estado es ready, directSsh da el host, el usuario y el puerto. Aumente su presupuesto con POST /v1/sessions/{id}/budget y deténgala con POST /v1/sessions/{id}/stop: la facturación termina y el resto del presupuesto se libera.

Si POST /v1/sessions responde 409 RESERVATION_REQUIRED, reserve la máquina con POST /v1/reservations (partnerOfferId y durationHours, o mode: "on_demand") e iníciela con POST /v1/reservations/{id}/start. Una duración fija retiene su precio completo, y maxCostCents rechaza la reserva si ese importe lo superara. Bajo demanda, el importe retenido cubre los próximos 60 minutos y se renueva mientras la máquina funciona. En ambos casos se le factura por minuto iniciado de uso real, sin mínimo de una hora.

Para controlar sesiones desde un agente de IA, use el servidor MCP.

Límites de gasto

Cada clave puede llevar límites, que Node Lodge aplica al lanzar una sesión, al aumentar su presupuesto y cada vez que se prolonga una reserva bajo demanda:

Un lanzamiento o un aumento que superaría un límite responde 409 API_KEY_LIMIT y no reserva nada. Las solicitudes simultáneas con una misma clave se comprueban una tras otra, así que no pueden superar un límite juntas. Una clave sin límites sigue acotada por su crédito disponible y los límites de su cuenta. Los propietarios y administradores cambian los límites de una clave activa con Edit limits en Keys, tras un código de dos factores reciente. Las sesiones lanzadas desde la consola no están limitadas por ninguna clave.

La configuración de la cuenta, las claves, las claves SSH guardadas, las tarjetas y la autenticación de dos factores se gestionan en la consola: una solicitud con clave de API a esas rutas responde 403 API_KEY_NOT_ALLOWED. Cada acción realizada con una clave figura en Activity, con la clave que la hizo.

Errores

Los cuerpos de error tienen la misma forma en todas partes:

{ "error": { "code": "API_KEY_NOT_ALLOWED", "message": "...", "reference": "7F3K-92QD" } }

reference identifica la solicitud. Regístrela con el error e inclúyala cuando escriba al soporte.

Proteger las claves

• Guarde las claves en su gestor de secretos o en los secretos de su CI, nunca en el código.
• Una clave por herramienta, para revocar una sin afectar a las demás.
• Revoque una clave en Keys en cuanto se filtre. Las solicitudes que la usan se detienen de inmediato.
• Cada creación y revocación de clave figura en Activity.