# Device Agent API

The Device Agent API is the JSON protocol used by the official
[`probo-agent`](/docs/product/device-agent/overview). You can implement this
protocol to enroll devices and report posture from operating systems,
appliances, or environments that the official agent does not yet support.

Dispozitivul inițiază fiecare cerere; platforma nu poate trimite comenzi, scripturi sau verifica definiții la acesta.

## Base URL

Append `/api/agent/v1` to the origin of the the platform deployment where the device
was created.

| Deployment  | Base URL                                 |
| ----------- | ---------------------------------------- |
| US cloud    | `https://us.probo.com/api/agent/v1`      |
| EU cloud    | `https://eu.probo.com/api/agent/v1`      |
| Self-hosted | `https://probo.example.com/api/agent/v1` |

APIeste destinat agenților nativi, nu clienților browser-ului și nu expune accesul browser-ului de origine încrucișată.

## Device states

Fiecare înregistrare a dispozitivului se mișcă printr-o mașină de stat mic. Numai Agentul dispozitivuluiAPIși revocarea administratorului schimbă aceste stări după creare.

| State     | Meaning                                                               |
| --------- | --------------------------------------------------------------------- |
| `PENDING` | Enrollment token issued; no successful heartbeat yet                  |
| `ACTIVE`  | First heartbeat succeeded; heartbeats and posture uploads are allowed |
| `REVOKED` | Enrollment ended by an administrator or by `/unenroll`                |

The first successful `/heartbeat` activates a `PENDING` device. `/postures`
requires `ACTIVE`. A revoked device cannot be un-revoked; create a new device
and enroll again.

## Protocol lifecycle

Diagrama de secvență arată înscrierea, ritmul cardiac independent și programele de postură și cele două moduri în care se încheie înscrierea unui agent.

Intervalele de ritm cardiac și de postură sunt valori separate returnate de fiecare ritm cardiac reușit. Tratați fiecare ca pe un temporizator propriu. Serverul returnează metadatele de programare, dar nu trimite niciodată lucrări dispozitivului. vezi [ZebraByteDevice Agent security](/docs/product/device-agent/security) pentru modelul de limită de securitate și de amenințare.

## Implementation checklist

- Accept the the platform origin and enrollment token as separate inputs.
- Require HTTPS outside local development and reject server URLs containing
  credentials, query strings, or fragments.
- Store the device API key in an OS-appropriate secret store or a file readable
  only by the service account.
- Send `Content-Type: application/json` and `Accept: application/json`.
- Identify the implementation with a `User-Agent`, such as
  `my-probo-agent/1.0.0`.
- Send a successful `/heartbeat` before the first `/postures` request.
- Honor the intervals returned by every successful heartbeat as separate
  timers.
- Batch no more than 100 posture results in one request.
- Do not log enrollment tokens, API keys, or sensitive posture evidence.
- On `401 Unauthorized` after activation, stop reporting and clear the device
  API key.

## Reference implementation

Utilizați agentul oficial ca referință de lucru atunci când implementați protocolul:

- [`cmd/probo-agent`](/docs)
- [`pkg/deviceagent`](/docs)

Preferă să contribuie la agentul oficial atunci când schimbarea aparține binarului partajat. vezi [Contribuie laZebraByteDevice Agent](/docs/developers/api/agent/contribute) pentru căile sursă, cerințele DCO și linia de timp de revizuire a securității.

Dacă aveți nevoie de asistență mai devreme decât permite ciclul oficial de lansare, implementați acestAPIîn propriul agent.

## Next steps

- [Autentificare](/docs/developers/api/agent/autentificare) – Schimbarea unui token de înregistrare și protejarea dispozitivuluiAPIcheie – [Endpoints](/docs/developers/api/agent/endpoints) – Implementare înregistrare, bătăi de inimă, postură și dezinscriere – [Contribuire](/docs/developers/api/agent/contribuire) – Contribuie la agentul oficial și ce să se aștepte de la revizuire