Device Agent API

The JSON protocol used by probo-agentYou can deploy this protocol to record devices and report posture from operating systems, devices, or environments that the official agent does not yet support.

The device initiates each application; the platform cannot send commands, scripts, or check definitions to it.

Base URL

Add /api/agent/v1 to the deployment source of the platform on which 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

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

Device states

Each record of the device moves through a small state machine.Only the device agent and administrator revocation changes these states after creation.

State	Meaning
PENDING	Enrollment token issued; no successful heartbeat yet
ACTIVE	The first heartbeat succeeded; heartbeats and posture are allowed
REVOKED	Record completed by an administrator or by /unenroll

The first success /heartbeat activates a device PENDING. /postures requires ACTIVE.

Protocol lifecycle

The sequence chart shows the entry, independent heart rate and posture schedules and the two ways in which an agent’s entry 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

The heart rate and posture intervals are separate values returned by each successful heart rate. Treat each as its own timer. The server returns the programming metadata but never sends work to the device. ZebraByte Device Agent security Border security and threat model.

Implementation checklist

• Accept the platform’s origin and the sign-up token as separate entries.
• Requires HTTPS outside of local development and rejects server URLs that contain credentials, query strings, or fragments.
• Stores the device key in a secret store corresponding to the operating system or in a file that can only be read by the service account.
• You can send Content-Type: application/json and Accept: application/json.
• Identify the implementation with a User-Agent, such as my-probo-agent/1.0.0.
• Successfully send /heartbeat before the first request /postures.
• Honour the returned intervals of each successful heartbeat as separate timers.
• Batch no more than 100 results in one application.
• Do not register entry tokens, API keys, or sensitive posture evidence.
• At 401 Unauthorized after activation, stop reporting and delete the device keyAPI.

Reference implementation

Use the official agent as a work reference when deploying the protocol:

• cmd/probo-agent
• pkg/deviceagent

You prefer to contribute to the official agent when the change belongs to the shared binary. Join the Agent Platform For source pathways, DCO requirements and security review chronology. Withdrawal requests that reach the device agent can take longer to merge as we review them widely for endpoint security.

If you need support earlier than the official launch cycle allows, deploy this API in your own agent.

Next steps

Authentication Change a registry token and protect the device key

Endpoints Implement enrollment, heartbeat, posture, and unenrollment

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