f1fbe0e29a
Archived 4 completed OpenSpec changes (2026-04-02): - phase-3-enterprise (100/100 tasks) — 6 Phase 3 capabilities synced - devops-documentation (48/48 tasks) — 3 new + 1 merged capability - bedroom-developer-docs (33/33 tasks) — 4 new capabilities synced - engineering-docs (superseded by 2026-03-29 archive) — no tasks Main spec library grows from 21 → 35 capabilities (+14 new): federation, multi-tenancy, oidc, soc2, w3c-dids, webhooks, database, operations, system-overview, api-reference, core-concepts, developer-guides, quick-start + deployment (merged additive requirements) Active changes: 0 — project board is clear for Phase 4 planning. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
51 lines
5.2 KiB
Markdown
51 lines
5.2 KiB
Markdown
## 1. Folder Structure & Setup
|
|
|
|
- [x] 1.1 Create `docs/developers/` directory
|
|
- [x] 1.2 Create `docs/developers/guides/` subdirectory
|
|
- [x] 1.3 Create `docs/developers/README.md` — index page listing all docs with one-line descriptions and links
|
|
|
|
## 2. Quick-Start Guide
|
|
|
|
- [x] 2.1 Create `docs/developers/quick-start.md` — prerequisites section (Docker + curl only)
|
|
- [x] 2.2 Write Step 1: start infrastructure with docker-compose command + confirmation of services and ports
|
|
- [x] 2.3 Write Step 2: start AgentIdP server with npm command + expected startup output
|
|
- [x] 2.4 Write Step 3: register an agent — complete curl for `POST /agents` with example request body and expected JSON response
|
|
- [x] 2.5 Write Step 4: generate a credential — complete curl for `POST /agents/{agentId}/credentials` with example response showing `clientId` and `clientSecret`
|
|
- [x] 2.6 Write Step 5: issue an access token — complete curl for `POST /token` with form-encoded body and example JWT response
|
|
- [x] 2.7 Write "What's Next" section linking to concepts.md, guides/README.md, and api-reference.md
|
|
|
|
## 3. Core Concepts Guide
|
|
|
|
- [x] 3.1 Create `docs/developers/concepts.md` — intro section: what is AgentIdP in one paragraph
|
|
- [x] 3.2 Write "What is an AI Agent Identity" section — plain-English explanation of agent identities vs human identities
|
|
- [x] 3.3 Write "AGNTCY Alignment" section — what AGNTCY is, why it matters, benefit to the developer (no external reading required)
|
|
- [x] 3.4 Write "Agent Lifecycle" section — four states (active, suspended, decommissioned) and what each means for credentials and tokens, including irreversibility of decommission
|
|
- [x] 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
|
|
- [x] 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
|
|
|
|
- [x] 4.1 Create `docs/developers/guides/README.md` — index listing all four guides with descriptions and links
|
|
- [x] 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)
|
|
- [x] 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)
|
|
- [x] 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
|
|
- [x] 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
|
|
|
|
- [x] 5.1 Create `docs/developers/api-reference.md` — top section: base URL, port config via env var, versioning note (Phase 1 unversioned)
|
|
- [x] 5.2 Write table of contents linking to all four service sections
|
|
- [x] 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
|
|
- [x] 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
|
|
- [x] 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
|
|
- [x] 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
|
|
- [x] 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
|
|
|
|
- [x] 6.1 Verify all curl examples are syntactically correct and complete (no ellipses, no missing flags)
|
|
- [x] 6.2 Verify all 14 endpoints from the OpenAPI specs are covered in api-reference.md
|
|
- [x] 6.3 Verify all internal links (cross-references between docs) resolve correctly
|
|
- [x] 6.4 Verify free-tier limits in concepts.md match README.md Section 3.3
|
|
- [x] 6.5 Verify quick-start guide is self-contained — a developer can complete it using only that file
|