Admin API

Tu flota, gestionada por código.

Todo lo que puedes hacer por app en el panel también funciona como llamada REST: crear app IDs con código de enrolamiento, listar tu flota, desactivar o eliminar apps. Pensada para scripts y agentes de IA — una API key estática, JSON simple, sin SDK.

Autenticación

Crea una API key en el panel, en Ajustes → API keys. La clave (pz_live_…) se muestra una sola vez — guárdala bien. Envíala como token Bearer en cada petición:

curl https://poisonzero.com/api/v1/apps \
  -H "Authorization: Bearer pz_live_..."

Endpoints

`POST /v1/apps`

Crea una app y un código de enrolamiento en una sola llamada. Body opcional: {"name": "…"} (máx. 100 caracteres). Responde 201 con appId, enrollCode y enrollCodeExpiresAt — todo lo que una máquina necesita para enrolarse.

curl -X POST https://poisonzero.com/api/v1/apps \
  -H "Authorization: Bearer $PZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "build-server-07"}'

`GET /v1/apps`

Lista tu flota: appId, name, status (pending / active / revoked), platform, agentVersion, lastSeenAt, createdAt.

curl https://poisonzero.com/api/v1/apps -H "Authorization: Bearer $PZ_API_KEY"

`GET /v1/apps/{appId}`

Devuelve una sola app. Los IDs desconocidos — incluidas apps ajenas — responden 404.

curl https://poisonzero.com/api/v1/apps/k7x2m9q4w1bz8r3tj6vn -H "Authorization: Bearer $PZ_API_KEY"

`POST /v1/apps/{appId}/enroll-code`

Crea un código de enrolamiento nuevo para una app existente, p. ej. para reaprovisionar una máquina. Los códigos son de un solo uso y válidos 30 días.

curl -X POST https://poisonzero.com/api/v1/apps/k7x2m9q4w1bz8r3tj6vn/enroll-code -H "Authorization: Bearer $PZ_API_KEY"

`POST /v1/apps/{appId}/revoke`

Desactiva una app: el estado pasa a revoked y las credenciales del daemon dejan de funcionar de inmediato. Mismo efecto que «Revocar» en el panel.

curl -X POST https://poisonzero.com/api/v1/apps/k7x2m9q4w1bz8r3tj6vn/revoke -H "Authorization: Bearer $PZ_API_KEY"

`DELETE /v1/apps/{appId}`

Elimina una app de forma permanente: app, configuración, identidad del daemon, códigos de enrolamiento abiertos y sus entradas de la cola de revisión. Los logs de auditoría se conservan. Responde 204.

curl -X DELETE https://poisonzero.com/api/v1/apps/k7x2m9q4w1bz8r3tj6vn -H "Authorization: Bearer $PZ_API_KEY"

Aprovisionar 50 daemons en un bucle

Cada llamada devuelve un app ID más su código de enrolamiento — listos para tu automatización de flota (Ansible, bucle SSH, MDM). Los daemons se enrolan solos en el primer arranque:

for i in $(seq -w 1 50); do
  curl -s -X POST https://poisonzero.com/api/v1/apps \
    -H "Authorization: Bearer $PZ_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"daemon-$i\"}"
done

Errores

Todos los errores comparten la misma forma: {"error": {"code": "…", "message": "…"}}. 401 — clave ausente/inválida/revocada o cuenta deshabilitada. 404 — endpoint desconocido o app ID desconocido/ajeno. 400 — validación (p. ej. invalid_name, limit_reached).

Legible por máquinas: versión Markdown · spec OpenAPI 3. La facturación no cambia: los daemons activos se miden cada noche, sin importar cómo se crearon.