Device Agent Authentication

The device agent uses two credentials for different purposes:

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

Both credentials are hexadecimal string 96 characters. the platform only stores their SHA-256 hashes.

Enrollment tokens

A sign-up token belongs to a single device record. It is single-use and expires after seven days by default.

Create your device and get its token before calling the Device AgentAPI:

• In the platform console, use the recording stream of the device.
• Through the graphQLAPI console, use createDevice or enrollDevice.
• Through MCP is used the tool ___ZBT_I18N_RUNTIME_BLOCK_172__.
• Prin intermediul CLI, utilizarea prb device create.
• Prinn8n, utilizaţi device create operation.

These interfaces return the URL of the platform server alongside the token. The creation of the device is not part of /api/agent/v1.

Protect enrollment tokens

Do not enter a sign-up token in a regular web URL, log, shell history or chat message. Anyone who changes it before it expires receives the API key of the device.

Exchange a token

Send the token once to the server URL provided with the entry:

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>"
}

Reusing it, using an expired token or using an unknown token returns 401 Unauthorized.

The official agent stores it in its state directory with restricted access to the service account. a custom agent can use the secret store of the operating system instead.

Authenticate device requests

Send the key to the device to the carrier token at each end point except /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"
  }'

The key remains valid until the device is revoked by an administrator or discarded by the agent. the platform displays the simple text key only in the sign-up response.

Handle unauthorized responses

Treat any 401 Unauthorized response from an authenticated endpoint as a dead credential:

1. Stop heartbeat and posture uploads.
2. Delete the key and the line posture data from the local storage.
3. Requires a new registration device and registration token.

Do not retry a rejected API key indefinitely.

An important exception during bringing: /postures also returns 401 when the device is still PENDING because a successful heartbeat has not yet been activated. Active with /heartbeat before loading the first post so that a valid key is not removed as revoked.

Desktop enrollment links

The official desktop stream can pass the subscription entry through this custom URI:

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

If your agent implements this stream, securely record the probo scheme, validate that server is an HTTPS source, reject unexpected parameters and avoid URI recording.

Next step

See Endpoints for request and response schemes.