sentryagent-idp/docs/developers/guides/agntcy-compliance.md

AGNTCY Compliance

This guide explains how to use AgentIdP's AGNTCY compliance features: exporting agent cards, generating compliance reports, verifying audit chain integrity, and checking SOC 2 control status.

---

Prerequisites

• A running AgentIdP instance
• COMPLIANCE_ENABLED environment variable not set to false (enabled by default)
• A valid Bearer token (for authenticated endpoints)
• At least one registered agent

---

What is AGNTCY?

AGNTCY is an open standard from the Linux Foundation for AI agent identity and governance. AgentIdP implements AGNTCY by giving every agent a DID and an agent card. The compliance endpoints let you export and report on that data in structured, auditable formats.

---

Export agent cards

GET /api/v1/compliance/agent-cards

Exports all active agents in your organization as AGNTCY-standard agent card JSON objects. Suitable for ingestion by external compliance tools or AGNTCY-compatible registries.

curl -s "http://localhost:3000/api/v1/compliance/agent-cards" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response (200 OK): Array of agent card objects.

[
  {
    "did": "did:web:localhost%3A3000:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "screener-001@talent.ai",
    "agentType": "screener",
    "capabilities": ["resume:read", "email:send"],
    "owner": "talent-team",
    "version": "1.0.0",
    "deploymentEnv": "production",
    "identityProvider": "https://sentryagent.ai",
    "issuedAt": "2026-04-04T09:00:00.000Z"
  }
]

Use cases:

• Share with external auditors to demonstrate your agent fleet
• Import into AGNTCY-compatible discovery registries
• Baseline snapshot before and after deployments

Save the output to a file:

curl -s "http://localhost:3000/api/v1/compliance/agent-cards" \
  -H "Authorization: Bearer $TOKEN" > agent-cards-$(date +%Y%m%d).json

---

Generate a compliance report

GET /api/v1/compliance/report

Generates an AGNTCY compliance report for your tenant. The report is cached for 5 minutes (check the X-Cache header to see if the response is fresh or cached).

curl -s "http://localhost:3000/api/v1/compliance/report" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response (200 OK):

{
  "tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
  "generatedAt": "2026-04-04T09:00:00.000Z",
  "agntcyConformance": true,
  "agentCount": 12,
  "verifiedAgentCount": 12,
  "auditChainIntegrity": true,
  "from_cache": false
}

Interpreting the fields:

Field	Description
agntcyConformance	true if all agents have valid DIDs and the audit chain is intact
agentCount	Total active agents in the organization
verifiedAgentCount	Agents with a resolvable DID document
auditChainIntegrity	true if the audit event hash chain has not been tampered with
from_cache	true if served from Redis cache (up to 5 minutes old)

Force a fresh report: Wait 5 minutes for the cache to expire. The from_cache: false response is always freshly generated.

---

Verify audit chain integrity

GET /api/v1/audit/verify

Verifies that the cryptographic hash chain of audit events is intact. Returns verified: true if no tampering is detected. Rate limited to 30 requests/minute (computationally intensive).

Requires: Bearer token with audit:read scope.

curl -s "http://localhost:3000/api/v1/audit/verify" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response (200 OK):

{
  "verified": true,
  "checkedCount": 1247,
  "fromDate": null,
  "toDate": null
}

Verify a specific date window:

curl -s "http://localhost:3000/api/v1/audit/verify?fromDate=2026-03-01T00:00:00.000Z&toDate=2026-03-31T23:59:59.999Z" \
  -H "Authorization: Bearer $TOKEN" | jq .

Interpreting the result:

• verified: true — no tampering detected in the checked window
• verified: false — the hash chain has a broken link; contact SentryAgent.ai support
• checkedCount — number of audit events verified

---

Check SOC 2 control status (public)

GET /api/v1/compliance/controls

Returns the live status of all SOC 2 Trust Services Criteria controls. No authentication required. Responses are cached by CDN/proxies for 60 seconds (Cache-Control: public, max-age=60).

curl -s "http://localhost:3000/api/v1/compliance/controls" | jq .

Response (200 OK):

{
  "controls": [
    {
      "id": "CC6.1",
      "name": "Logical Access Controls",
      "status": "pass",
      "lastChecked": "2026-04-04T08:00:00.000Z"
    },
    {
      "id": "CC7.2",
      "name": "System Monitoring",
      "status": "pass",
      "lastChecked": "2026-04-04T08:00:00.000Z"
    }
  ]
}

Each control has a status of pass, fail, or unknown. Status is updated by background jobs that run periodically. This endpoint is suitable for embedding in external status pages or compliance dashboards without sharing API credentials.

---

When compliance endpoints are disabled

If COMPLIANCE_ENABLED=false is set in the server environment, the AGNTCY compliance endpoints (/compliance/report and /compliance/agent-cards) return 404 COMPLIANCE_DISABLED. The SOC 2 endpoints (/compliance/controls and /audit/verify) are never gated and always active.