L'API de gestion
Tout ce que vous faites par app dans la 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 la console 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 la console 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 l'agent poison0.