TigerTrust agents run inside customer infrastructure (Linux/Windows/macOS hosts, Kubernetes clusters) and talk to the Collector service. The Collector authenticates agents with API keys of type agent (ak_... prefix) and mediates all task orchestration, CSR intake, and discovery result submission. Base URL — typically https://collector.<your-domain> in production. All Collector routes are documented here relative to that host.
Collector responses are plain JSON objects, not the { data: ... } envelope used by the main API. Field names remain camelCase.

​
Authentication

Every /api/collector/* route requires an agent API key. Send it either as: 
X-Agent-API-Key: ak_9f2a3b4c...7c4e
or as a Bearer token: 
Authorization: Bearer ak_9f2a3b4c...7c4e
The header name is configurable via the collector’s auth.api_key_header config (default X-Agent-API-Key). Failed authentication returns 401 with one of invalid API key, API key has expired, API key has been revoked, or API key not authorized for agent access. Agents are workspace-scoped — an agent belongs to the workspace of the API key that registered it. Attempts to access agents in a different workspace return 403 agent does not belong to this workspace.

​
Health

GET /health and GET /ready — public, unauthenticated: 
{ "status": "healthy", "service": "collector", "timestamp": "2026-08-25T14:22:03.812Z" }

​
Register (or re-register) an agent

POST /api/collector/agents/register Idempotent — sending the same id updates the existing agent’s config and status rather than creating a duplicate. On first registration the agent is bound to the API key’s workspace.
​
id
string
required
Stable agent identifier chosen by the agent (e.g. agent-dc1-01).
​
name
string
required
​
agentVersion
string
​
osType
string
linux, windows, darwin.
​
osVersion
string
​
hostname
string
​
machineId
string
Stable machine identifier used for host deduplication.
​
ipAddress
string
Falls back to r.RemoteAddr when omitted.
​
capabilities
string[]
e.g. ["file", "jks", "pkcs11", "aws-kms"].
​
config
object
Nested { discovery, kubernetes, cloud } blocks describing what the agent is willing to scan.
curl -X POST https://collector.tigertrust.example.com/api/collector/agents/register \
  -H "X-Agent-API-Key: ak_9f2a...7c4e" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "agent-dc1-01",
    "name": "DC1 Primary Agent",
    "agentVersion": "1.4.2",
    "osType": "linux",
    "hostname": "agent-dc1-01.corp.example.com",
    "machineId": "e3b0c44298fc1c14",
    "capabilities": ["file", "k8s", "jks", "pkcs11"],
    "config": {
      "discovery": { "local": { "enabled": true, "scanPaths": ["/etc/ssl"] } },
      "kubernetes": { "enabled": true, "namespaces": ["prod", "staging"] }
    }
  }'

{
  "message": "agent registered",
  "agentId": "agent-dc1-01",
  "hostId": "h_ac9b31...",
  "status": "active"
}
Repeat calls return 200 OK with "existing": true.

​
Poll for tasks

GET /api/collector/agents/:agentId/tasks Returns up to 10 pending tasks and atomically transitions each to in_progress. Agents should call this on a short interval (typically 5–15 s) between heartbeats.
​
tasks
AgentTask[]
​
count
integer
Each task carries id, taskType (csr_generation, cert_deploy, key_rotation, discovery, health_check), priority, payload (opaque JSON per task type), certificateId, maxRetries, scheduledFor, expiresAt.

​
Submit a task result

POST /api/collector/agents/:agentId/results
​
taskId
integer
required
​
success
boolean
required
​
data
object
Result payload — task-type-specific.
​
error
string
Populated when success=false.
Returns { "message": "result submitted", "taskId": 12345 }.

​
Heartbeat

POST /api/collector/agents/:agentId/heartbeat Records live agent telemetry and returns the count of tasks currently waiting so the agent can size its poll.
​
status
string
required
Typically active.
​
cpuUsage
number
​
memoryUsage
number
​
diskUsage
number
​
certificatesManaged
integer
​
pendingTasks
integer
​
lastError
string
{
  "message": "heartbeat recorded",
  "pendingTasks": 3,
  "serverTime": "2026-08-25T14:22:03.812Z"
}

​
Submit a CSR

POST /api/collector/agents/:agentId/csr Called when an agent completes a csr_generation task. The Collector stores the CSR result and records a keyReference (where the private key lives on the agent host), then triggers downstream renewal processing.
​
taskId
integer
required
​
csr
string
required
PEM-encoded CSR.
​
certificateId
integer
Target certificate this CSR is for.
​
keyAlgorithm
string
​
keySize
integer
​
keyReference
object
required
{ keyIdentifier, keyStore, keyPath } — where the private key is stored on the agent (PKCS#11 slot, KMS ARN, file path, etc.).
Returns { "message": "CSR submitted", "taskId", "keyReference" }.
When the Collector receives a CSR, it publishes an internal event to trigger immediate downstream renewal processing without waiting for the next scheduled check.

​
Submit discovery results

POST /api/collector/agents/:agentId/discovery Bulk-submit certificate discovery findings from an agent scan. Also used for startup inventories.
​
agentId
string
required
​
hostname
string
required
​
machineId
string
​
ipAddress
string
​
osType
string
​
osVersion
string
​
type
string
startup, rescan, or task.
​
scanId
integer
Discovery scan ID for progress tracking.
​
timestamp
string (ISO 8601)
required
​
results
object
required
DiscoveryResults payload containing certificates, totalScanned, totalFound.
{
  "message": "discovery results processed",
  "agentId": "agent-dc1-01",
  "type": "rescan",
  "new": 12,
  "updated": 3,
  "unchanged": 41,
  "processedAt": "2026-08-25T14:22:03.812Z"
}

​
Submit SSH key discovery

POST /api/collector/agents/:agentId/ssh-discovery Same shape as the certificate discovery endpoint but for SSH .pub files and authorized_keys entries.
​
keys
SSHKeyInfo[]
.pub file discoveries with { path, type, fingerprint, comment, bits, publicKey }.
​
authorizedKeys
AuthorizedKeyInfo[]
Entries with { filePath, username, hostname, lineNum, fingerprint, keyType, publicKey, options }.
​
serverFingerprint
string
SSH host key fingerprint of the scanned box.
​
totalScanned
integer
​
totalFound
integer
​
duration
number
Scan duration in seconds.
Response includes { new, updated, unchanged } key counts.

​
Agent status

GET /api/collector/agents/:agentId/status Lightweight probe used by the dashboard to render the agent card: 
{
  "agentId": "agent-dc1-01",
  "name": "DC1 Primary Agent",
  "status": "active",
  "lastHeartbeat": "2026-08-25T14:22:03.812Z",
  "pendingTasks": 3,
  "version": "1.4.2"
}

​
See also