L'API de gestion
Tout ce que vous faites par app dans le panneau console fonctionne aussi comme appel REST, de sorte qu'une flotte peut être provisionnée depuis la CI/CD, la gestion de configuration ou un MDM. Cette page est la référence des points de terminaison : ce que fait chaque appel, comment vous vous authentifiez, et pourquoi l'API ne voit jamais le contenu protégé.
De quoi il s'agit
- Une petite surface REST pour le cycle de vie des apps : créer, enrôler, lister, désactiver et supprimer des apps protégées.
- Conçue pour l'automatisation : intégrez un démon non enrôlé dans une image de référence et frappez les codes d'enrôlement à l'avance ; chaque machine s'enrôle elle-même au premier démarrage.
- Lisible par machine : une spécification OpenAPI 3 est publiée à côté de cette page.
Plan de gestion face au plan de données
La propriété décisive est ce que cette API ne voit pas. Le système a deux plans distincts :
| Plan | Trafic | Voit le contenu ? |
|---|---|---|
| Plan de gestion | Cette API : cycle de vie des apps et métadonnées uniquement (identifiant, nom, statut, plateforme, version de l'agent, horodatages, codes d'enrôlement). | Non : aucun contenu mémoire, aucun diff, aucune charge d'évaluation ne le traverse jamais. |
| Plan de données | Le trafic propre au démon : check-ins et, dans le flux assisté par le cloud, l'évaluation de diffs caviardés. | Le contenu reste sur l'appareil ; seule une projection caviardée est évaluée. |
Authentification
Les appelants s'authentifient avec une clé bearer créée dans le panneau sous Paramètres, clés API. La clé (pz_live_ suivi de quarante caractères) est affichée une seule fois ; au repos, seul son hachage SHA-256 est stocké, de sorte qu'une divulgation de base de données ne livre aucun identifiant utilisable.
curl -H "Authorization: Bearer pz_live_..." \ https://poisonzero.com/api/v1/apps
- Limitée au propriétaire : chaque requête est liée au propriétaire de la clé.
- Aucune énumération : une app étrangère ou inconnue répond un
404identique, de sorte que les identifiants hors de votre flotte ne peuvent pas être sondés. - Dix clés actives par compte ; toute clé peut être révoquée indépendamment.
Points de terminaison
Les points de terminaison reflètent le panneau et sont joints via HTTPS sur poisonzero.com/api/v1/. Chaque appel prend la clé bearer :
| Point de terminaison | Rôle | Renvoie |
|---|---|---|
POST /v1/apps | Crée une app et un premier code d'enrôlement en un appel (corps optionnel {"name":"..."}). | 201 avec appId, enrollCode, enrollCodeExpiresAt. |
GET /v1/apps | Liste votre flotte. | Une entrée par app (voir l'objet app ci-dessous). |
GET /v1/apps/{appId} | Récupère une app. | 404 pour les identifiants inconnus ou étrangers. |
POST /v1/apps/{appId}/enroll-code | Frappe un nouveau code d'enrôlement, par exemple pour re-provisionner une machine. | 201 ; les codes sont à usage unique et valables 30 jours. |
POST /v1/apps/{appId}/revoke | Désactive une app ; le statut devient revoked et les identifiants du démon cessent immédiatement de fonctionner. | appId et status. |
DELETE /v1/apps/{appId} | Supprime une app définitivement (app, configuration, identité du démon, codes ouverts, entrées de la file de revue ; les journaux d'audit sont conservés). | 204. |
GET / PUT / DELETE /v1/otel-config | Gère la configuration d'export OpenTelemetry de la flotte (Enterprise). | Voir la page d'export d'observabilité. |
GET et PUT sur /v1/otel-config exigent un propriétaire Enterprise (sinon 403) ; DELETE est toujours autorisé afin qu'un propriétaire rétrogradé puisse encore purger un secret de collecteur stocké. L'export lui-même : export OpenTelemetry.L'objet app
Lister et récupérer renvoient les métadonnées de cycle de vie de chaque app, jamais le contenu :
| Champ | Signification |
|---|---|
appId | Identifiant d'app stable. |
name | Nom d'affichage. |
status | pending, active ou revoked. |
platform | Système d'exploitation rapporté. |
agentVersion | Version du démon rapportée. |
lastSeenAt, createdAt | Horodatages. |
Transport
- HTTPS sur
poisonzero.com/api/v1/; un proxy inverse ne transmet que la méthode, le chemin, l'en-tête d'autorisation, le type de contenu et un corps à taille plafonnée. - Le chemin est décodé jusqu'à un point fixe et tout segment de point ou barre oblique inverse est rejeté, fermant les tentatives de traversée de chemin.
- La gestion de flotte n'est pas conditionnée à un abonnement actif, de sorte que vous pouvez provisionner et révoquer pendant qu'un plan est en cours d'arrangement.
Erreurs
Toutes les erreurs partagent une seule forme, {"error":{"code":"...","message":"..."}}, avec un code lisible par machine stable :
| Statut | Signification |
|---|---|
400 | Validation, par exemple invalid_name ou limit_reached. |
401 | Clé manquante, invalide ou révoquée, ou compte désactivé. |
404 | Point de terminaison inconnu, ou identifiant d'app inconnu ou étranger. |
413 | Corps de requête au-delà de 64 Kio (payload_too_large). |
429 | Trop de requêtes ; ralentissez et réessayez (jusqu'à 600 par minute par compte). |
/docs/api/openapi.json.À lire ensuite
L'export Enterprise configuré via /v1/otel-config : export OpenTelemetry. Où les codes d'enrôlement servent au déploiement : installer PoisonZero.
Provisionnez toute votre flotte depuis un script.
Créez, enrôlez et révoquez via REST, avec une seule clé API statique. L'API ne voit jamais le contenu protégé.
Sign me up