Device Agent Authentication

Agentul de dispozitivAPIutilizează două credențiale cu scopuri diferite:

Credential	Purpose	Sent as
Enrollment token	One-time exchange for a device API key	token în corpul /enroll
Device API key	Heartbeat, posture, and unenrollment requests	Authorization: Bearer <api-key>

Ambele credențiale sunt șiruri hexadecimale de 96 de caractere. platforma stochează numai hash-urile lor SHA-256 .

Enrollment tokens

Un token de înscriere aparține unei singure înregistrări a dispozitivului. Este de unică folosință și expiră după șapte zile în mod implicit.

Creați dispozitivul și obțineți tokenul său înainte de a apela Agentul dispozitivuluiAPI:

• În consola platformă, utilizați fluxul de înregistrare a dispozitivului.
• Prin intermediul consoleiGraphQLAPI, utilizați createDevice sau enrollDevice.
• Prin intermediulMCPse utilizează instrumentul ___ZBT_I18N_RUNTIME_BLOCK_172__.
• Prin intermediul CLI, utilizarea prb device create.
• Prinn8n, utilizaţi device create operation.

Aceste interfețe returnează adresa URL a serverului platformei alături de token. Crearea dispozitivului nu face parte din /api/agent/v1.

Protect enrollment tokens

Nu introduceți un token de înscriere într-un URL web obișnuit, jurnal, istoric de shell sau mesaj de chat. Oricine îl schimbă înainte de expirarea acestuia primește cheiaAPIa dispozitivului.

Exchange a token

Trimiteți tokenul o dată la URL-ul serverului furnizat cu înscrierea:

US

curl --request POST \
  --url https://us.probo.com/api/agent/v1/enroll \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"token":"<enrollment-token>"}'

EU

curl --request POST \
  --url https://eu.probo.com/api/agent/v1/enroll \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"token":"<enrollment-token>"}'

Self-hosted

curl --request POST \
  --url https://probo.example.com/api/agent/v1/enroll \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"token":"<enrollment-token>"}'

A successful exchange returns:

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

Reutilizarea acestuia, folosind un token expirat sau folosind un token necunoscut returnează 401 Unauthorized.

Persistați cheiaAPIînainte de a începe serviciul. agentul oficial îl stochează în directorul său de stat cu acces restricționat la contul de serviciu. un agent personalizat poate folosi magazinul secret al sistemului de operare în schimb.

Authenticate device requests

Trimiteți cheia dispozitivuluiAPIca token purtător pe fiecare punct final, cu excepția /enroll:

Authorization: Bearer <device-api-key>

For example:

curl --request POST \
  --url https://us.probo.com/api/agent/v1/heartbeat \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <device-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "hardware_uuid": "example-hardware-id",
    "hostname": "example-device",
    "platform": "LINUX",
    "os_version": "Example Linux 1.0",
    "agent_version": "1.0.0"
  }'

CheiaAPIrămâne valabilă până când dispozitivul este revocat de un administrator sau dezinserat de agent. platforma afișează cheia de text simplu numai în răspunsul de înscriere.

Handle unauthorized responses

Tratați orice răspuns 401 Unauthorized dintr-un punct final autentificat ca o credențială moartă:

1. Stop heartbeat and posture uploads.
2. Ștergeți cheiaAPIși datele posturii în coadă din stocarea locală.
3. Necesită un nou dispozitiv de înregistrare și token de înregistrare.

Do not retry a rejected API key indefinitely.

O excepție importantă în timpul aducerii: /postures returnează, de asemenea, 401 atunci când dispozitivul este încă PENDING deoarece nu a fost activată încă o bătăi de inimă de succes. Activă cu /heartbeat înainte de încărcarea primei posturi, astfel încât o cheie valabilă să nu fie eliminată ca revocată.

Desktop enrollment links

Fluxul oficial de desktop poate trece intrarea de înscriere prin această URI particularizată:

probo://enroll?server=https%3A%2F%2Fus.probo.com&token=<enrollment-token>

Dacă agentul dvs. implementează acest flux, înregistrați în siguranță schema probo, validați faptul că server este o origine HTTPS, respingeți parametrii neașteptate și evitați înregistrarea URI-ului.

Next step

See Endpoints pentru schemele de solicitare și răspuns.