sentryagent-idp/openspec/changes/archive/2026-04-02-bedroom-developer-docs/tasks.md

1. Folder Structure & Setup

• 1.1 Create docs/developers/ directory
• 1.2 Create docs/developers/guides/ subdirectory
• 1.3 Create docs/developers/README.md — index page listing all docs with one-line descriptions and links

2. Quick-Start Guide

• 2.1 Create docs/developers/quick-start.md — prerequisites section (Docker + curl only)
• 2.2 Write Step 1: start infrastructure with docker-compose command + confirmation of services and ports
• 2.3 Write Step 2: start AgentIdP server with npm command + expected startup output
• 2.4 Write Step 3: register an agent — complete curl for POST /agents with example request body and expected JSON response
• 2.5 Write Step 4: generate a credential — complete curl for POST /agents/{agentId}/credentials with example response showing clientId and clientSecret
• 2.6 Write Step 5: issue an access token — complete curl for POST /token with form-encoded body and example JWT response
• 2.7 Write "What's Next" section linking to concepts.md, guides/README.md, and api-reference.md

3. Core Concepts Guide

• 3.1 Create docs/developers/concepts.md — intro section: what is AgentIdP in one paragraph
• 3.2 Write "What is an AI Agent Identity" section — plain-English explanation of agent identities vs human identities
• 3.3 Write "AGNTCY Alignment" section — what AGNTCY is, why it matters, benefit to the developer (no external reading required)
• 3.4 Write "Agent Lifecycle" section — four states (active, suspended, decommissioned) and what each means for credentials and tokens, including irreversibility of decommission
• 3.5 Write "OAuth 2.0 Client Credentials" section — plain-English explanation of client_id, client_secret, and how agents use them; no RFC jargon
• 3.6 Write "Free Tier Limits" section — table of all four limits (100 agents, 10k tokens/month, 100 req/min, 90-day audit) with notes on what happens when each is exceeded

4. Developer Guides

• 4.1 Create docs/developers/guides/README.md — index listing all four guides with descriptions and links
• 4.2 Create docs/developers/guides/register-an-agent.md — step-by-step registration guide with all required/optional fields, validation rules, and example success + error responses (including common validation errors and fixes)
• 4.3 Create docs/developers/guides/manage-credentials.md — guide covering all four credential operations: generate (with secret handling note), list (with pagination), rotate (explaining same credentialId, old secret immediately invalid), revoke (with comparison to agent decommission)
• 4.4 Create docs/developers/guides/issue-and-revoke-tokens.md — token guide covering: issuance with form-encoded body, JWT structure explanation, using token as Bearer in subsequent requests, introspection (active field), revocation and immediate invalidation
• 4.5 Create docs/developers/guides/query-audit-logs.md — audit log guide covering: available filters (agentId, action, outcome, date range), pagination params, audit event structure, 90-day retention behaviour

5. API Reference

• 5.1 Create docs/developers/api-reference.md — top section: base URL, port config via env var, versioning note (Phase 1 unversioned)
• 5.2 Write table of contents linking to all four service sections
• 5.3 Write errors reference section: all error response shapes, all custom error codes (ValidationError, AgentNotFoundError, AgentAlreadyExistsError, CredentialError, AuthenticationError, AuthorizationError, RateLimitError, FreeTierLimitError), HTTP status mappings
• 5.4 Document Agent Registry endpoints (5): POST /agents, GET /agents, GET /agents/{agentId}, PATCH /agents/{agentId}, DELETE /agents/{agentId} — each with method, path, auth requirement, request fields table, response codes table, and complete curl example
• 5.5 Document OAuth 2.0 Token endpoints (3): POST /token, POST /token/introspect, POST /token/revoke — each with method, path, auth requirement, request fields table (noting form-encoded for /token), response codes table, curl example, and X-RateLimit header documentation for 429s
• 5.6 Document Credential Management endpoints (4): POST /agents/{agentId}/credentials, GET /agents/{agentId}/credentials, POST /agents/{agentId}/credentials/{credentialId}/rotate, DELETE /agents/{agentId}/credentials/{credentialId} — each with method, path, auth requirement, request fields table, response codes table, and complete curl example
• 5.7 Document Audit Log endpoints (2): GET /audit, GET /audit/{eventId} — each with method, path, auth requirement, query parameter table (including all filter options), response codes table, and complete curl example

6. QA & Review

• 6.1 Verify all curl examples are syntactically correct and complete (no ellipses, no missing flags)
• 6.2 Verify all 14 endpoints from the OpenAPI specs are covered in api-reference.md
• 6.3 Verify all internal links (cross-references between docs) resolve correctly
• 6.4 Verify free-tier limits in concepts.md match README.md Section 3.3
• 6.5 Verify quick-start guide is self-contained — a developer can complete it using only that file