sentryagent-idp/docs/agntcy/alignment.md

AGNTCY Alignment Mapping

This document maps each AGNTCY standard concept to the corresponding AgentIdP implementation. It is the authoritative reference for AGNTCY compliance claims.

---

AGNTCY Core Concepts

AGNTCY defines five foundational concepts for AI agent identity:

AGNTCY Concept	Description
Non-Human Identity	Agents are first-class identities — not service accounts, not user proxies
Agent Registry	Authoritative directory of registered agent identities with stable, immutable IDs
Credential Management	Secure issuance, rotation, and revocation of agent credentials
Authentication	Standardised protocol for agents to prove their identity
Lifecycle Management	Defined states for agent provisioning, suspension, and retirement
Audit and Accountability	Immutable event log of all agent actions for governance and compliance

---

Implementation Mapping

Non-Human Identity

AGNTCY requires agents to be treated as first-class identities with their own identity model — not mapped onto human user accounts.

AGNTCY Requirement	AgentIdP Implementation	Status
Unique, immutable agent identifier	agentId (UUID, system-assigned at registration, never changes)	✅ Implemented
Human-readable stable name	email field — unique email-format identifier per agent	✅ Implemented
Identity metadata	agentType, version, capabilities, owner, deploymentEnv fields	✅ Implemented
Capability declaration	capabilities array — resource:action strings declaring agent permissions	✅ Implemented
Identity separate from human users	Agents have their own registry, credential model, and token flow — no user accounts	✅ Implemented

API endpoints: POST /api/v1/agents, GET /api/v1/agents/{agentId}

---

Agent Registry

AGNTCY requires a centralised, queryable registry of agent identities.

AGNTCY Requirement	AgentIdP Implementation	Status
Register new agent identity	POST /api/v1/agents	✅ Implemented
Retrieve agent by stable ID	GET /api/v1/agents/{agentId}	✅ Implemented
List and filter registered agents	GET /api/v1/agents?owner=&agentType=&status=	✅ Implemented
Update agent metadata	PATCH /api/v1/agents/{agentId}	✅ Implemented
Soft-delete retired agents (record retained)	DELETE /api/v1/agents/{agentId} → status: decommissioned, record persisted	✅ Implemented
Enforce uniqueness of agent identity	email unique constraint — 409 AGENT_ALREADY_EXISTS on duplicate	✅ Implemented

---

Credential Management

AGNTCY requires secure credential issuance with rotation and revocation support.

AGNTCY Requirement	AgentIdP Implementation	Status
Issue agent credentials	POST /api/v1/agents/{agentId}/credentials — generates client_id + client_secret	✅ Implemented
Secret never stored in plaintext	client_secret stored as bcrypt hash; plaintext returned once only	✅ Implemented
Multiple active credentials per agent	An agent can hold multiple active credentials simultaneously	✅ Implemented
Credential rotation	POST /api/v1/agents/{agentId}/credentials/{credentialId}/rotate	✅ Implemented
Credential revocation	DELETE /api/v1/agents/{agentId}/credentials/{credentialId}	✅ Implemented
Credential lifecycle tracking	status field: active / revoked; revokedAt timestamp	✅ Implemented
Optional credential expiry	expiresAt field on credential generation	✅ Implemented

---

Authentication

AGNTCY requires a standardised, interoperable authentication protocol for agents.

AGNTCY Requirement	AgentIdP Implementation	Status
Standardised auth protocol	OAuth 2.0 Client Credentials grant (RFC 6749 §4.4)	✅ Implemented
Signed, verifiable tokens	RS256 JWT access tokens — any party with the public key can verify	✅ Implemented
Token introspection	POST /api/v1/token/introspect — RFC 7662 compliant	✅ Implemented
Token revocation	POST /api/v1/token/revoke — RFC 7009 compliant	✅ Implemented
Scope-based access control	agents:read, agents:write, tokens:read, audit:read scopes	✅ Implemented
Token lifetime enforcement	1-hour JWT expiry, enforced at verification	✅ Implemented
Revocation durability	Revocations persisted to PostgreSQL + Redis	✅ Implemented

Token claims align with AGNTCY identity model:

JWT Claim	AGNTCY Meaning
sub	The agent's stable agentId — the AGNTCY non-human identity reference
client_id	The credential that authenticated this token request
scope	Declared capabilities granted for this token
jti	Unique token ID — enables precise revocation

---

Lifecycle Management

AGNTCY defines a mandatory lifecycle for agent identities.

AGNTCY State	AgentIdP Status	Behaviour
Provisioned / Active	active	Agent can authenticate and obtain tokens
Suspended	suspended	Agent cannot obtain new tokens; existing tokens expire naturally
Decommissioned / Retired	decommissioned	Permanent — all credentials revoked, agent cannot authenticate, record retained

AGNTCY Requirement	AgentIdP Implementation	Status
Defined lifecycle states	status enum: active, suspended, decommissioned	✅ Implemented
Irreversible decommission	decommissioned status cannot be reversed via API	✅ Implemented
Credential cascade on decommission	All active credentials revoked when agent is decommissioned	✅ Implemented
State transitions audited	Every status change writes an agent.suspended, agent.reactivated, or agent.decommissioned audit event	✅ Implemented

---

Audit and Accountability

AGNTCY requires an immutable, queryable audit log of all significant agent actions.

AGNTCY Requirement	AgentIdP Implementation	Status
Immutable audit log	audit_events table — append-only, no API delete/update	✅ Implemented
Automatic event capture	12 event types captured automatically across all services	✅ Implemented
Query and filter audit events	GET /api/v1/audit with filters: agentId, action, outcome, fromDate, toDate	✅ Implemented
Retrieve individual event	GET /api/v1/audit/{eventId}	✅ Implemented
Event retention	90-day retention enforced at query layer (free tier)	✅ Implemented
Auth failure logging	auth.failed event on every failed POST /token attempt	✅ Implemented

Audited events (12 total):

Event	Trigger
agent.created	New agent registered
agent.updated	Agent metadata changed
agent.suspended	Agent suspended
agent.reactivated	Agent reactivated from suspended
agent.decommissioned	Agent permanently decommissioned
token.issued	Access token issued
token.revoked	Access token revoked
token.introspected	Token introspection called
credential.generated	New credentials generated
credential.rotated	Credential rotated
credential.revoked	Credential revoked
auth.failed	Authentication attempt failed

---

Compliance Status Summary

AGNTCY Domain	Phase 1 Status	Notes
Non-Human Identity	✅ Fully implemented	Immutable IDs, typed metadata, capability declarations
Agent Registry	✅ Fully implemented	Full CRUD, pagination, soft-delete
Credential Management	✅ Fully implemented	Generate, rotate, revoke, bcrypt storage
Authentication	✅ Fully implemented	OAuth 2.0 CC, RS256 JWT, introspect, revoke, scopes
Lifecycle Management	✅ Fully implemented	active / suspended / decommissioned with cascades
Audit and Accountability	✅ Fully implemented	12 event types, immutable, queryable, 90-day retention
Federation	🔲 Phase 2	Cross-system agent identity federation
W3C DIDs	🔲 Phase 3	Decentralised identifier support
Policy Engine	🔲 Phase 2	OPA-based capability enforcement
Secret Management	🔲 Phase 2	HashiCorp Vault integration

---

Interoperability

An agent registered in AgentIdP can be identified by any AGNTCY-compliant system using its agentId (UUID). The JWT access token carries the sub claim (= agentId), making the agent's identity verifiable by any party that holds the AgentIdP RS256 public key.

To verify an AgentIdP token in an external system:

1. Obtain the AgentIdP RS256 public key (JWT_PUBLIC_KEY from the server operator)
2. Verify the JWT signature using RS256
3. The sub claim is the agent's stable AGNTCY-aligned identity reference
4. The scope claim declares the agent's authorised capabilities for this token

This is the same verification model used across all OAuth 2.0 / OIDC systems — purpose-built for machine-to-machine interoperability.