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.

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

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

```json
[
  {
    "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:

```bash
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).

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

Response (`200 OK`):

```json
{
  "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.

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

Response (`200 OK`):

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

Verify a specific date window:

```bash
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`).

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

Response (`200 OK`):

```json
{
  "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.