Agent heartbeat
POST/api/v1/certops/agent/heartbeat
Steady-state heartbeat authenticated with the per-agent credential (bearer). Updates last_seen_at, records the envelope clockOffsetMs and body ntpSynced/uptimeSeconds/pinnedSigningKeyId for clock-drift and key-rotation fleet monitoring, flips an offline agent back to active, and announces the active job-signing public key. Request body is the agent-protocol envelope with messageType heartbeat (packages/contracts/certops/agent-protocol.schema.json, additionalProperties false). A retired agent authenticates but receives 410 without any last_seen_at update. Private key material is audited and rejected with 422. Hidden with 404 while certops.enabled is disabled.
Request
Responses
- 200
- 400
- 401
- 404
- 409
- 410
- 422
- 429
- 500
- 503
Heartbeat accepted with signing key announcement
Message envelope or heartbeat body failed agent-protocol validation
Per-agent credential missing, unknown, or revoked
CertOps is disabled deployment-wide (route is hidden)
Message sequence is not greater than the last accepted sequence for this agent
Agent is retired; last_seen_at is not updated
Request rejected because it contained private key material
CertOps machine-token rate limit exceeded
Internal server error
Security audit sink unavailable while rejecting private material