Device Agent API

The Device Agent API is the JSON protocol used by the official probo-agent. 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.

The protocol is deliberately small and push-only. The device initiates every request; Probo cannot send commands, scripts, or check definitions to it.

Base URL

Append /api/agent/v1 to the origin of the Probo 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

The API is intended for native agents, not browser clients, and does not expose cross-origin browser access.

Device states

Each device record moves through a small state machine. Only the Device Agent API and administrator revocation change these states after creation.

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

The sequence diagram shows enrollment, independent heartbeat and posture schedules, and the two ways an agent enrollment ends.

sequenceDiagram
  actor Admin as Organization administrator
  participant Probo as Probo server
  participant Agent as Device agent

  Admin->>Probo: Create device
  Probo-->>Admin: Server URL and one-shot enrollment token
  Admin->>Agent: Configure server URL and token

  Agent->>Probo: POST /enroll with token
  Probo-->>Agent: Device API key
  Agent->>Probo: POST /heartbeat with API key
  Probo-->>Agent: Device ID, heartbeat interval, posture interval, server time

  par Heartbeat schedule
    loop Every heartbeat_interval_seconds
      Agent->>Probo: POST /heartbeat with device identity
      Probo-->>Agent: Updated intervals and server time
    end
  and Posture schedule
    loop Every posture_interval_seconds
      Agent->>Agent: Run local posture checks
      Agent->>Probo: POST /postures with results
      Probo-->>Agent: 204 No Content
    end
  end

  alt Device is revoked
    Agent->>Probo: POST /heartbeat or /postures
    Probo-->>Agent: 401 Unauthorized
    Agent->>Agent: Stop reporting and delete API key
  else Agent is removed
    Agent->>Probo: POST /unenroll
    Probo-->>Agent: 204 No Content
    Agent->>Agent: Delete local credentials
  end

Heartbeat and posture intervals are separate values returned by every successful heartbeat. Treat each as its own timer. The server returns scheduling metadata, but it never sends work to the device. See Probo Agent security for the security boundary and threat model.

Implementation checklist

• Accept the Probo 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

Use the official agent as a working reference when implementing the protocol:

• cmd/probo-agent
• pkg/deviceagent

Prefer contributing to the official agent when the change belongs in the shared binary. See Contributing to Probo Agent for source paths, DCO requirements, and the security review timeline. Pull requests that touch the device agent can take longer to merge because we review them extensively for endpoint security.

If you need support sooner than the official release cycle allows, implement this API in your own agent instead.

Next steps

Authentication Exchange an enrollment token and protect the device API key

Endpoints Implement enrollment, heartbeat, posture, and unenrollment

Contributing Contribute to the official agent and what to expect from review