La API de gestión
Todo lo que haces por app en el panel de la consola también funciona como llamada REST, de modo que una flota puede aprovisionarse desde CI/CD, gestión de configuración o un MDM. Esta página es la referencia de endpoints: qué hace cada llamada, cómo te autenticas y por qué la API nunca ve el contenido protegido.
Qué es
- Una pequeña superficie REST para el ciclo de vida de las apps: crear, inscribir, listar, desactivar y eliminar apps protegidas.
- Hecha para la automatización: integra un daemon sin inscribir en una imagen base y acuña códigos de inscripción por adelantado; cada máquina se inscribe sola en el primer arranque.
- Legible por máquina: se publica una especificación OpenAPI 3 junto a esta página.
Plano de gestión frente a plano de datos
La propiedad decisiva es lo que esta API no ve. El sistema tiene dos planos distintos:
| Plano | Tráfico | ¿Ve el contenido? |
|---|---|---|
| Plano de gestión | Esta API: solo ciclo de vida de las apps y metadatos (identificador, nombre, estado, plataforma, versión del agente, marcas de tiempo, códigos de inscripción). | No: ningún contenido de memoria, ningún diff, ninguna carga de evaluación lo cruza jamás. |
| Plano de datos | El propio tráfico del daemon: check-ins y, en el flujo asistido por la nube, la evaluación de diffs censurados. | El contenido permanece en el dispositivo; solo se evalúa una proyección censurada. |
Autenticación
Quien llama se autentica con una clave bearer creada en el panel bajo Ajustes, claves API. La clave (pz_live_ seguida de cuarenta caracteres) se muestra una sola vez; en reposo solo se almacena su hash SHA-256, de modo que una divulgación de base de datos no entrega ninguna credencial utilizable.
curl -H "Authorization: Bearer pz_live_..." \ https://poisonzero.com/api/v1/apps
- Acotada al propietario: cada petición está ligada al propietario de la clave.
- Sin enumeración: una app ajena o desconocida responde un
404idéntico, de modo que no se pueden sondear identificadores fuera de tu flota. - Diez claves activas por cuenta; cualquier clave puede revocarse de forma independiente.
Endpoints
Los endpoints reflejan el panel y se alcanzan vía HTTPS en poisonzero.com/api/v1/. Cada llamada toma la clave bearer:
| Endpoint | Función | Devuelve |
|---|---|---|
POST /v1/apps | Crea una app y un primer código de inscripción en una llamada (cuerpo opcional {"name":"..."}). | 201 con appId, enrollCode, enrollCodeExpiresAt. |
GET /v1/apps | Lista tu flota. | Una entrada por app (ver el objeto app más abajo). |
GET /v1/apps/{appId} | Recupera una app. | 404 para identificadores desconocidos o ajenos. |
POST /v1/apps/{appId}/enroll-code | Acuña un nuevo código de inscripción, por ejemplo para reaprovisionar una máquina. | 201; los códigos son de un solo uso y válidos 30 días. |
POST /v1/apps/{appId}/revoke | Desactiva una app; el estado pasa a revoked y las credenciales del daemon dejan de funcionar de inmediato. | appId y status. |
DELETE /v1/apps/{appId} | Elimina una app de forma permanente (app, configuración, identidad del daemon, códigos abiertos, entradas de la cola de revisión; los registros de auditoría se conservan). | 204. |
GET / PUT / DELETE /v1/otel-config | Gestiona la configuración de exportación OpenTelemetry de la flota (Enterprise). | Ver la página de exportación de observabilidad. |
GET y PUT en /v1/otel-config exigen un propietario Enterprise (si no, 403); DELETE siempre se permite para que un propietario degradado pueda aún purgar un secreto de colector almacenado. La exportación en sí: exportación OpenTelemetry.El objeto app
Listar y recuperar devuelven los metadatos de ciclo de vida de cada app, nunca el contenido:
| Campo | Significado |
|---|---|
appId | Identificador de app estable. |
name | Nombre visible. |
status | pending, active o revoked. |
platform | Sistema operativo reportado. |
agentVersion | Versión del daemon reportada. |
lastSeenAt, createdAt | Marcas de tiempo. |
Transporte
- HTTPS en
poisonzero.com/api/v1/; un proxy inverso solo reenvía el método, la ruta, la cabecera de autorización, el tipo de contenido y un cuerpo con tope de tamaño. - La ruta se decodifica hasta un punto fijo y se rechaza todo segmento de punto o barra invertida, cerrando los intentos de traversía de ruta.
- La gestión de flota no está condicionada a una suscripción activa, de modo que puedes aprovisionar y revocar mientras se organiza un plan.
Errores
Todos los errores comparten una sola forma, {"error":{"code":"...","message":"..."}}, con un código legible por máquina estable:
| Estado | Significado |
|---|---|
400 | Validación, por ejemplo invalid_name o limit_reached. |
401 | Clave ausente, inválida o revocada, o cuenta desactivada. |
404 | Endpoint desconocido, o identificador de app desconocido o ajeno. |
413 | Cuerpo de petición por encima de 64 KiB (payload_too_large). |
429 | Demasiadas peticiones; reduce el ritmo y reintenta (hasta 600 por minuto por cuenta). |
/docs/api/openapi.json.Sigue leyendo
La exportación Enterprise configurada por /v1/otel-config: exportación OpenTelemetry. Dónde sirven los códigos de inscripción en el despliegue: instalar PoisonZero.
Aprovisiona toda tu flota desde un script.
Crea, inscribe y revoca vía REST, con una sola clave API estática. La API nunca ve el contenido protegido.
Sign me up