Device Agent Endpoints

Toate rutele Agentului dispozitivuluiAPIfolosesc POST și sunt relative la {probo-origin}/api/agent/v1.

Endpoint	Authentication	Success response
`/enroll`	Enrollment token in body	`200` JSON
`/heartbeat`	Device API key	`200` JSON
`/postures`	Device API key	`204`
`/unenroll`	Device API key	`204`

Request headers

Trimiteți aceste titluri cu fiecare cerere:

Accept: application/json
Content-Type: application/json
User-Agent: my-probo-agent/1.0.0

Pentru fiecare rută, cu excepția /enroll, trimiteți și:

Authorization: Bearer <device-api-key>

User-Agent este recomandat pentru rezolvarea problemelor și nu este utilizat pentru autentificare.

Enroll

Schimbă un token de înscriere cu o singură lovitură pentru o cheieAPI.

POST /api/agent/v1/enroll

Corpul solicitării este limitat la 16 KiB.

Request

{
  "token": "<enrollment-token>"
}

Field	Type	Required	Description
`token`	string	Yes	One-shot enrollment token

Response

200 OK

{
  "api_key": "<device-api-key>"
}

Stocați în siguranță cheia înainte de a începe serviciul. tokenul de înscriere este șters după un schimb de succes și nu poate fi reutilizat.

Heartbeat

Raportează identitatea dispozitivului și recuperează programul de raportare. Primul ritm cardiac reușit schimbă un dispozitiv PENDING în ACTIVE. Intervalele de ritm cardiac și de postură sunt independente; actualizați fiecare timer local din răspuns.

POST /api/agent/v1/heartbeat
Authorization: Bearer <device-api-key>

Corpul solicitării este limitat la 16 KiB.

Request

{
  "hardware_uuid": "example-hardware-id",
  "serial_number": "example-serial-number",
  "hostname": "example-device",
  "platform": "LINUX",
  "os_version": "Example Linux 1.0",
  "agent_version": "1.0.0"
}

Field	Type	Required	Description
`hardware_uuid`	string	Yes	Stable hardware identifier
`serial_number`	string	No	Hardware serial number
`hostname`	string	Yes	Current device hostname
`platform`	string	Yes	Una dintre valorile platformei acceptate de mai jos
`os_version`	string	Yes	Human-readable operating-system version
`agent_version`	string	Yes	Versiunea de implementare a agentului de raportare

Valorile valabile ___ZBT_I18N_RUNTIME_BLOCK_202__ sunt:

Value	Platform
`DARWIN`	macOS
`LINUX`	Linux
`FREEBSD`	FreeBSD
`WINDOWS`	Windows

UUID-ul hardware-ului trebuie să fie stabil pe tot parcursul restartului. platforma respinge activarea dacă un alt dispozitiv din organizație îl folosește deja.

Response

200 OK

{
  "device_id": "<device-id>",
  "heartbeat_interval_seconds": 300,
  "posture_interval_seconds": 3600,
  "server_time": "2026-08-05T14:00:00Z"
}

Field	Type	Description
`device_id`	string	identificatorul platformei pentru dispozitivul înregistrat
`heartbeat_interval_seconds`	integer	Delay between heartbeat requests
`posture_interval_seconds`	integer	Delay between posture collection cycles
`server_time`	string	Current server time in RFC 3339 UTC format

Tratează răspunsul ca fiind autoritativ: actualizează fiecare timer local după fiecare bătăi ale inimii reușite, în loc să codezi aceste valori sau să presupui că programele rămân în loc.

Postures

Apelează la o serie de verificări ale posturii evaluate la nivel local. Dispozitivul trebuie să fi transmis o bătăi ale inimii înainte de a raporta postura. O cerere de postură în timp ce dispozitivul este încă PENDING returnează 401 Unauthorized – același statut utilizat pentru revocare – deci activați mai întâi cu /heartbeat.

POST /api/agent/v1/postures
Authorization: Bearer <device-api-key>

Corpul de solicitare este limitat la 1 MiB și poate conține până la 100 de rezultate.

Request

{
  "results": [
    {
      "check_key": "FIREWALL_ENABLED",
      "status": "PASS",
      "evidence": {
        "backend": "ufw",
        "raw": "Status: active"
      },
      "observed_at": "2026-08-05T14:00:00Z"
    }
  ]
}

Field	Type	Required	Description
`results`	array	Yes	Up to 100 posture results
`check_key`	string	Yes	Identificator stabil pentru verificare
`status`	string	Yes	Result status
`evidence`	JSON object	No	Details supporting the result
`observed_at`	string	Yes	Observation time in RFC 3339 format
`correlation_id`	string	No	ID-ul posture-report al platformei utilizat pentru gruparea seturilor de rezultate asociate

O matrice goală results este acceptată ca non-op. O solicitare reușită returnează 204 No Content.

Status values

Value	Meaning
`PASS`	The check passed
`FAIL`	The check failed
`UNKNOWN`	Agentul nu a putut stabili rezultatul
`NOT_APPLICABLE`	Verificarea nu se aplică acestui dispozitiv

Canonical check keys

Utilizați cheile oficiale atunci când cecul dvs. are același sens. Acest lucru permite platformei să interpreteze și să afișeze dovezile în mod consecvent.

Check key	What it evaluates
`DISK_ENCRYPTION`	Full-disk encryption
`SCREEN_LOCK`	Screen or idle-lock configuration
`FIREWALL_ENABLED`	Host firewall
`TIME_SYNC`	System clock synchronization
`OS_VERSION`	Operating-system version
`AUTO_UPDATE`	Automatic operating-system updates
`PASSWORD_POLICY`	Local password policy
`REMOTE_LOGIN`	Remote-login exposure
`MALWARE_PROTECTION`	Built-in malware protection

APIacceptă alte chei de verificare necompletate, dar platforma ar putea afișa dovezile lor ca necunoscute.

Evidence

Evidența este JSON în formă liberă. Preferați un obiect cu câmpuri concise care pot fi citite de mașină. Nu includeți secrete, fișiere de configurare complete sau ieșiri de comandă care ar putea conține date personale sau sensibile.

Schemele de dovezi ale agentului oficial sunt cea mai bună referință atunci când se pune în aplicare o verificare canonică. checks package.

Correlation IDs

Dacă correlation_id este omis, platforma creează un ID și îl aplică fiecărui rezultat din cerere.

Furnizați un ID de corelație numai atunci când aveți deja un ID de raportare a poziției dispozitivului platformei valabil pentru același locatar. ID-uri invalide, ID-uri pentru un alt tip de entitate și ID-uri de la un alt locatar returnează 400 Bad Request.

Unenroll

Revokes the current device API key.

POST /api/agent/v1/unenroll
Authorization: Bearer <device-api-key>

Nu sunt necesare câmpuri de cerere. O cerere reușită returnează 204 No Content. Ștergeți credențialele locale indiferent dacă această cerere cu cele mai bune eforturi reușește în timpul dezinstalării.

Errors

Status	Meaning
`400`	JSON invalid, câmpuri lipsă, enum invalid sau lot supradimensionat
`401`	Token de înregistrare invalid, cheieAPIlipsă/invalidă, revocare sau postură înainte de activare
`405`	Ruta a fost apelată cu o altă metodă decât `POST`
`500`	Unexpected server error

Nu vă bazați pe mesajul exact de eroare. Înregistrați starea și contextul solicitării securizate fără a înregistra acreditările sau dovezile posturii. Retrificați eșecurile temporare ale rețelei și răspunsurile ___ZBT_I18N_RUNTIME_BLOCK_258__ cu backlink exponențial limitat. Nu retrificați răspunsurile ___ZBT_I18N_RUNTIME_BLOCK_259__ fără a schimba solicitarea și Credențiale clare după 401 cu excepția cazului în care o cerere de postură precede prima bătăi de inimă reușite.