Device Agent Endpoints

All Device Agent API routes use POST Acestea 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

Pe toate drumurile, cu excepţia /enroll, also send:

Authorization: Bearer <device-api-key>

User-Agent este recomandată pentru depanare și nu este utilizată pentru autentificare.

Enroll

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

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. PENDING device to ACTIVEBătăile inimii și intervalele 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

Valid platform values are:

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 de inimă reușite înainte de a raporta postura. PENDING returns 401 Unauthorizedaceeaşi stare utilizată pentru revocare – deci activaţi cu /heartbeat first.

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

An empty results array este acceptat ca un no-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

API acceptă 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

Rezultatele dintr-un ciclu de colectare ar trebui să aparțină unui raport de postură. correlation_id dacă este omis, platforma creează un singur 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 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 solicitare. O solicitare reușită returnează 204 No ContentȘtergeți credențialele locale, indiferent dacă această cerere cu cel mai bun efort 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, cheie API lipsă/invalidă, revocare sau postură înainte de activare
405	Ruta a fost numită printr-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 credențiale sau dovezi de postură. 5xx răspunsuri cu backoff exponențial limitat. nu repetați 400 răspunsuri fără a modifica cererea; și clear credentials after 401 cu excepția cazului în care o cerere de postură precede prima bătăi de inimă reușite.