Agent identity, traceability & signed evidence

Key takeaways

• Start with one quick-start API key if you want easy discovery; use separate production keys by agent, tool, department, or environment when you want stronger isolation.
• Every API key is bound to a verified base agent. A caller-declared actor.agent_id becomes a claimed child agent until an admin verifies it, scopes it, or blocks it.
• Send trace_id (and parent_trace_id for sub-agents) to link a whole run; attach tool_calls[], sub_agents[], and retrieved_context[] for full traceability.
• Least agency: per-agent scopes (action types, departments, risk caps) enforced as warn or strict; strict out-of-scope returns 403.
• Always Discovery mode: unknown agents are recorded, never blocked — but you can block any agent, and blocked agents are rejected with 403.
• GET /requests/:id/evidence and /agents/:id/evidence return an HMAC-signed contro1.request.v2 packet you can verify with your org webhook secret.

The capabilities ladder

You can do everything below, and you can adopt it one rung at a time. Each step is a small addition to the request you already send — start at the top and go as deep as you need.

First agent in 10 minutes

For a pilot, create one API key in Settings and send your first request. Contro1 creates a verified base agent for that key, then discovers any actor.agent_id values as claimed child agents in Agent Inventory.

After traffic appears, open Agent Inventory and promote the agents you trust: verify them, assign an owner or department, set least-agency scopes, define who can approve risky actions, and export signed evidence when you need proof.

• Create a quick-start key in Settings -> APIs & Webhooks.
• Send POST /v1/requests with actor.agent_id and, when available, trace_id.
• Open Agent Inventory to see verified base agents and claimed children.
• Verify important agents, scope permissions, configure approval routing, or block unknown agents.
• Use Signed evidence on the agent row, or GET /v1/agents/:id/evidence, to export proof.

Agent identity (verified vs claimed)

Identity starts with the authenticated API key. When you create a key in Settings it is bound to a verified base agent, created from the integration or label unless you bind the key to an existing agent.

For onboarding, one key can front many agents. If a request or audit record carries actor.agent_id that differs from the key's base agent, Contro1 records it as a claimed child under that base. The admin then reviews it in Agent Inventory, verifies or blocks it, assigns ownership, and sets scopes and approval paths.

A runtime caller cannot turn itself into another verified agent just by sending that agent_id. If the declared identity belongs somewhere else, Contro1 keeps it as a claimed child/alias under the authenticated key so the conflict is visible instead of trusted.

• verified — bound to an API key, or promoted by an admin. Trusted identity for ownership, scopes, approvals, and evidence.
• claimed — caller-asserted child or alias, awaiting admin verification.
• An admin verifies a claimed agent in the Agent Inventory tab, or via POST /admin/agents/:id/verify.

curl -X POST https://api.contro1.com/api/centcom/v1/requests \
  -H "Authorization: Bearer $CONTRO1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "approval",
    "title": "Refund $4,200 to customer 8831",
    "source": { "integration": "langgraph" },
    "actor": { "agent_id": "billing-subagent", "agent_name": "Billing Sub-Agent" },
    "continuation": { "mode": "decision" }
  }'

Tracing a run: trace_id, tool_calls, sub_agents, retrieved_context

trace_id (format trc_...) groups every request and audit record from one agent run. parent_trace_id attaches a sub-agent run to its parent, forming the span tree behind GET /v1/traces/:trace_id. These are distinct from thread_id (conversation) and correlation_id (business case) — send whichever you have.

Attach the traceability arrays to turn an audit trail into real traceability — what happened, why, which tools ran, and on what data.

Provenance matters for evidence quality. tool_calls, retrieved_context, and the triggering event are machine-observed when your gate or middleware recorded them from the runtime; any justification or summary the model wrote is agent-reported. Record both, label them apart, and never let agent-reported text raise or lower routing, risk_level, or approval policy. An auditor reading the packet later must be able to tell which statements are facts your code captured and which are the agent's own claims.

{
  "request_type": "approval",
  "title": "Publish generated incident summary",
  "source": { "integration": "openai-agents" },
  "trace_id": "trc_9f2c…",
  "tool_calls": [
    { "name": "search_kb", "output_summary": "3 matching runbooks", "outcome": "success" },
    { "name": "draft_summary", "output_summary": "412 tokens", "outcome": "success" }
  ],
  "retrieved_context": [
    { "source": "runbook:db-failover", "uri": "kb://runbooks/db-failover", "score": 0.82 }
  ],
  "continuation": { "mode": "instruction" }
}

Least agency (per-agent authority)

Each agent carries scopes that bound what it may do: allowed_action_types, allowed_department_ids, max_risk_level, and require_approval_above. enforcement is warn (allow but flag) or strict (block out-of-scope actions).

Under strict enforcement, an out-of-scope request is rejected before anything is created and returns HTTP 403 with an agent_policy_blocked error. Under warn, the request proceeds but the policy warning is attached to the decision context and, above require_approval_above, human approval is forced.

Discovery mode & the blocklist

Contro1 is always discovery-first: an unknown agent is recorded as claimed and shown in the inventory, so teams can connect quickly without pre-registering every agent. Shadow agents surface on their own.

For production, graduate important agents into verified identities with owners, department scopes, approval hierarchy, and evidence expectations. When you do not trust an agent, block it. A blocked agent joins the Blocked list and every subsequent call it makes is rejected with HTTP 403. Unblock it at any time.

# Block an agent (admin session)
curl -X POST https://api.contro1.com/api/centcom/admin/agents/agt_1a2b…/block \
  -H "Content-Type: application/json" \
  -d '{ "reason": "unrecognized source, investigating" }'

# A blocked agent's next request:
# HTTP 403 { "error": "agent_policy_blocked", "policy_reason": "agent_blocked", "agent_id": "agt_1a2b…" }

Signed evidence (contro1.request.v2)

GET /v1/requests/:id/evidence returns a JSON evidence packet that now includes the verified agent block, the trace, tool_calls, sub_agents, retrieved_context, and an integrity signature. GET /v1/agents/:id/evidence returns a signed bundle of every packet for one agent (or ?format=csv).

The integrity block is an HMAC-SHA256 signature over the canonical packet, computed with your organization webhook secret — the same secret used for signed callbacks. Recompute it to prove a packet has not been altered.

{
  "evidence_packet_version": "contro1.request.v2",
  "agent": { "agent_id": "agt_1a2b…", "name": "Billing Agent", "verification": "verified" },
  "trace": { "trace_id": "trc_9f2c…", "parent_trace_id": null },
  "tool_calls": [ { "name": "search_kb", "outcome": "success" } ],
  "retrieved_context": [ { "source": "runbook:db-failover" } ],
  "approval_records": [ { "operator_id": "…", "decision": "approved" } ],
  "integrity": { "alg": "HMAC-SHA256", "key_id": "a1b2c3…", "signed_at": "…", "signature": "…" }
}

Webhooks & signed callbacks · Audit records & cases · API endpoint index

Make the approval the gate, not a suggestion

The signed webhook is cryptographic proof of a human decision. Verify it inside the system that executes the action - not inside the agent. Any tool that must never run without human sign-off (payments, deploys, data deletion) should refuse to act without a verified approval; that way no agent, including shadow agents nobody registered, can trigger it by skipping Contro1.

• Verify the signature and reject timestamps older than 5 minutes (replay protection; the timestamp marks callback delivery, not request creation, so long SLAs are unaffected).
• Bind the approval to the exact action parameters via metadata / correlation_id - never treat "an approval arrived" as permission for a different action.
• Execute each request_id exactly once (idempotency on your side).
• When in doubt, confirm state directly with GET /v1/requests/:id using a read-only API key.

Full guardrail pattern with code: Webhooks

Frequently asked questions

Do I have to register my agents up front?

No. You can start with one quick-start key and let agents appear in the inventory the first time they call. You only act when you want to verify a claimed agent, scope its authority, route approvals by owner or hierarchy, or block it.

Can a caller fake another agent's identity?

No. The verified identity is derived from the authenticated API key. A caller-supplied actor.agent_id can only ever create a claimed sub-agent, which is clearly marked until an admin verifies it.

How do I verify an evidence packet?

Recompute the HMAC-SHA256 over the canonical packet (excluding the integrity field) using your organization webhook secret and compare it to integrity.signature. The SDKs expose a helper, or use the same routine as signed webhook verification.

Related resources