Device Agent Authentication

Agentul de dispozitiv API utilizează două credențiale cu scopuri diferite:

Credential	Purpose	Sent as
Enrollment token	One-time exchange for a device API key	token in the /enroll body
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 dispozitivului API:

• În consola platformă, utilizați fluxul de înregistrare a dispozitivului.
• Prin intermediul consolei GraphQLAPI, utilizaţi createDevice or enrollDevice.
• Prin MCP, utilizaţi createDevice tool.
• Prin intermediul CLI, utilizarea prb device create.
• Prin n8n, utilizaţi device create operation.

Aceste interfețe returnează URL-ul serverului platformei alături de token. /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 cheia API a 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>"
}

Serverul șterge tokenul de înregistrare după schimb. Reutilizarea acestuia, utilizarea unui token expirat sau utilizarea unui token necunoscut returnează 401 Unauthorized.

Persistați cheia API î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 dispozitivului API ca 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"
  }'

Cheia API ră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

Treat any 401 Unauthorized Răspunsul de la un endpoint autentificat ca acreditare moartă:

1. Stop heartbeat and posture uploads.
2. Ștergeți cheia API ș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.

One important exception during bring-up: /postures also returns 401 Atunci când dispozitivul este PENDING pentru că nici o bătăi ale inimii nu a activat-o încă. /heartbeat înainte de încărcarea primei poziții, 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 probo scheme securely, validate that server este de origine HTTPS, respinge parametrii neașteptati și evită înregistrarea URI. Un URI particularizat este opțional; fluxurile de comandă și de instalare gestionate pot trece serverul și tokenul separat.

Next step

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