vijay_admin/sentryagent-idp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: bedroom developer documentation — complete docs/developers/ set

Browse Source 
Adds the full bedroom-developer-docs OpenSpec change implementation:

- docs/developers/README.md — index page
- docs/developers/quick-start.md — bootstrap to working token in 7 steps
- docs/developers/concepts.md — AgentIdP, AGNTCY, lifecycle, OAuth 2.0, free tier
- docs/developers/guides/README.md — guide index
- docs/developers/guides/register-an-agent.md — all fields, validation, common errors
- docs/developers/guides/manage-credentials.md — generate, list, rotate, revoke
- docs/developers/guides/issue-and-revoke-tokens.md — OAuth 2.0 flow, introspect, revoke
- docs/developers/guides/query-audit-logs.md — filters, pagination, 90-day retention
- docs/developers/api-reference.md — all 14 endpoints, all error codes, curl examples

Also commits deferred OpenSpec housekeeping from previous session:
- Archives phase-1-mvp-implementation change to openspec/changes/archive/
- Adds bedroom-developer-docs change artifacts (30/30 tasks complete)
- Syncs 4 delta specs to openspec/specs/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SentryAgent.ai Developer
2026-03-28 14:13:03 +00:00
parent d3530285b9
commit 61ea975c79
29 changed files with 2397 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
openspec/changes/bedroom-developer-docs/.openspec.yaml Normal file
View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-03-28

63
openspec/changes/bedroom-developer-docs/design.md Normal file
View File

@@ -0,0 +1,63 @@
## Context
Phase 1 MVP is complete: 46 source files, 14 API endpoints across 4 OpenAPI 3.0 specs, 244 passing tests. The implementation is production-grade and live on `git.sentryagent.ai`. However, the developer experience stops at the code. There is no entry point for a bedroom developer who has never heard of AgentIdP, AGNTCY, or client credentials OAuth 2.0.
The documentation must be written, owned, and maintained as a first-class deliverable — not an afterthought. It is produced by a Virtual Technical Writer subagent with full access to the codebase and OpenAPI specs.
**Constraints:**
- Audience: bedroom developers — assume competence with HTTP and basic programming, assume no prior knowledge of AgentIdP or AGNTCY
- Format: Markdown only — renders on GitHub, no external tooling required
- No build step — docs are static `.md` files in `docs/developers/`
- All code examples must be real, runnable, and copy-pasteable
- Tone: direct, practical, no enterprise jargon
## Goals / Non-Goals
**Goals:**
- Bedroom developer can register their first agent and issue a token in under 5 minutes using only the quick-start guide
- Every API endpoint is documented in plain English with at least one working curl example
- Core concepts are explained without assuming prior knowledge of OAuth 2.0 or AGNTCY
- All four P0 workflows (register, credential, token, audit) have step-by-step guides
- FAQ covers the most likely failure points and free-tier limits
**Non-Goals:**
- No web-rendered documentation site (Phase 2 — out of scope)
- No SDK documentation (Node.js SDK not yet built — Phase 1 P1 remaining)
- No video tutorials or interactive demos
- No multi-language code examples (Node.js + curl only for now)
- No enterprise deployment documentation (separate from bedroom developer focus)
## Decisions
**Decision 1: Single flat folder vs nested structure**
Chosen: flat `docs/developers/` with a `tutorials/` subfolder only for multi-step guides.
Alternative considered: deep nesting by category. Rejected — adds navigation friction for a small doc set.
**Decision 2: Raw OpenAPI YAML as API reference vs human-written reference**
Chosen: human-written `api-reference.md` alongside the existing OpenAPI specs.
Alternative considered: link to raw YAML only. Rejected — YAML is not readable for bedroom developers; the whole point is accessibility.
**Decision 3: Standalone docs vs inline code comments**
Chosen: standalone Markdown files in `docs/developers/`.
Alternative considered: JSDoc-generated docs. Rejected — JSDoc is for library consumers, not REST API users.
**Decision 4: Who writes the docs**
Chosen: Virtual Technical Writer subagent — spawned by CTO with full codebase + OpenAPI spec context.
Alternative considered: Virtual Principal Developer writes docs. Rejected — developer time should stay on code; writing accessible prose for non-technical audiences is a distinct skill warranting a dedicated role.
**Decision 5: Versioning**
Chosen: docs live in the same repo as code, versioned together via git. No separate docs versioning scheme in Phase 1.
## Risks / Trade-offs
- **[Risk] Docs drift from implementation** → Mitigation: Virtual QA Engineer verifies API reference examples against actual endpoints before sign-off; curl examples are tested against a running instance
- **[Risk] Tone inconsistency across docs** → Mitigation: Technical Writer receives a unified style brief in the subagent prompt (plain English, second person, imperative voice, no jargon)
- **[Risk] Quick-start prerequisites unclear** → Mitigation: Quick-start lists exact prerequisites (Docker, curl, nothing else) and links to docker-compose.yml
## Migration Plan
Documentation only — no migration required. Files are added to `docs/developers/` and committed to `develop`. No rollback needed.
## Open Questions
*(none — scope is fully defined)*

34
openspec/changes/bedroom-developer-docs/proposal.md Normal file
View File

@@ -0,0 +1,34 @@
## Why
SentryAgent.ai AgentIdP Phase 1 MVP is fully implemented, tested, and live — but there is zero human-readable documentation for the developers we are building this for. A bedroom developer landing on this repo today cannot register their first agent without reading raw OpenAPI YAML or diving into source code. We fix that now.
## What Changes
- New `docs/developers/` folder containing a complete, self-contained documentation set for bedroom developers
- Quick-start guide: first agent registered and authenticated in under 5 minutes
- Core concepts doc: plain-English explanation of AgentIdP, AGNTCY alignment, and the agent identity model
- Step-by-step guides: agent registration, credential management, token issuance, audit log queries
- Human-friendly API reference: every endpoint documented with real curl examples and response samples
- FAQ: common errors, gotchas, and free-tier limits explained
- All docs written for a bedroom developer audience — no enterprise jargon, no assumed knowledge
## Capabilities
### New Capabilities
- `quick-start`: 5-minute guide from zero to first authenticated agent request — install, register, credential, token, done
- `core-concepts`: Plain-English explanation of what AgentIdP is, how it relates to AGNTCY, the agent identity lifecycle, and why it matters
- `developer-guides`: Step-by-step tutorials for the four core workflows: registering an agent, managing credentials, issuing and revoking tokens, querying the audit log
- `api-reference`: Human-friendly API reference covering all 14 endpoints with real examples, field descriptions, error codes, and rate limit notes
### Modified Capabilities
*(none — this change introduces documentation only; no existing API specs are modified)*
## Impact
- New folder: `docs/developers/` (7 markdown files)
- No code changes — documentation only
- No new dependencies
- No API changes
- Existing `docs/openapi/` specs are reference material for the Technical Writer but are not modified

50
openspec/changes/bedroom-developer-docs/specs/api-reference/spec.md Normal file
View File

@@ -0,0 +1,50 @@
## ADDED Requirements
### Requirement: API reference exists at docs/developers/api-reference.md
The system SHALL provide a human-readable API reference at `docs/developers/api-reference.md` covering all 14 endpoints across the four services: Agent Registry, OAuth 2.0 Token, Credential Management, and Audit Log.
#### Scenario: Developer finds any endpoint within 10 seconds
- **WHEN** the developer opens the API reference
- **THEN** they SHALL find a table of contents at the top linking to each of the four service sections
### Requirement: Every endpoint is documented with method, path, description, and auth requirements
For each of the 14 endpoints, the reference SHALL document: HTTP method, path, one-sentence description, and whether Bearer token auth is required.
#### Scenario: Developer knows which endpoints require authentication
- **WHEN** the developer scans the reference
- **THEN** they SHALL clearly see which endpoints require a Bearer token (all except POST /token) and which do not
### Requirement: Every endpoint includes a complete curl example
For each endpoint, the reference SHALL include at least one complete, runnable curl example with real placeholder values.
#### Scenario: Developer copies a curl example and runs it
- **WHEN** the developer copies a curl example from the reference
- **THEN** the command SHALL be complete — no ellipses, no `...`, no missing flags — requiring only substitution of their own agentId, token, and base URL
### Requirement: Every endpoint documents all request parameters and body fields
For each endpoint that accepts a request body or query parameters, the reference SHALL list every field with: name, type, required/optional, description, and validation constraints.
#### Scenario: Developer knows what fields are required for POST /agents
- **WHEN** the developer reads the POST /agents section
- **THEN** they SHALL see a table listing every field, its type, whether it is required, and any constraints (e.g. email format, max length)
### Requirement: Every endpoint documents all response codes and response body schemas
For each endpoint, the reference SHALL document every possible HTTP response code (2xx and 4xx/5xx) with a description and example response body.
#### Scenario: Developer understands a 429 response
- **WHEN** the developer reads the rate limit error documentation
- **THEN** they SHALL understand what triggered it, what the X-RateLimit-* headers mean, and when they can retry
### Requirement: API reference includes a base URL and versioning section
The reference SHALL include a section at the top explaining the base URL convention, port configuration, and that all endpoints are unversioned in Phase 1.
#### Scenario: Developer knows where to send requests
- **WHEN** the developer reads the base URL section
- **THEN** they SHALL see the default base URL (http://localhost:3000), how to change the port via environment variable, and a note that versioning will be introduced in Phase 2
### Requirement: API reference includes an errors section
The reference SHALL include a dedicated errors section listing all standard error response shapes, all custom error codes, and their HTTP status code mappings.
#### Scenario: Developer handles an AgentNotFoundError
- **WHEN** the developer reads the errors section
- **THEN** they SHALL see the exact JSON shape of the error response, the error code string, and the HTTP status (404)

43
openspec/changes/bedroom-developer-docs/specs/core-concepts/spec.md Normal file
View File

@@ -0,0 +1,43 @@
## ADDED Requirements
### Requirement: Core concepts guide exists at docs/developers/concepts.md
The system SHALL provide a concepts guide at `docs/developers/concepts.md` that explains the AgentIdP model in plain English with no assumed prior knowledge of AGNTCY or OAuth 2.0.
#### Scenario: Developer understands what AgentIdP is
- **WHEN** a developer reads the concepts guide
- **THEN** they SHALL be able to explain in one sentence what SentryAgent.ai AgentIdP does and why they need it
### Requirement: Concepts guide explains what an AI agent identity is
The guide SHALL explain in plain English what it means to give an AI agent an identity — how it differs from a human user account and why agents need their own identity model.
#### Scenario: Agent identity vs human identity distinction is clear
- **WHEN** the developer reads the agent identity section
- **THEN** they SHALL understand that agents are non-human, machine-operated identities that need persistent, auditable credentials — not session-based logins
### Requirement: Concepts guide explains the AGNTCY alignment
The guide SHALL explain what AGNTCY is (Linux Foundation standard), why SentryAgent.ai aligns to it, and what benefit that gives the developer — without requiring the developer to read the AGNTCY specification.
#### Scenario: Developer understands AGNTCY without external reading
- **WHEN** the developer reads the AGNTCY section
- **THEN** they SHALL understand that AGNTCY-aligned agent IDs are interoperable across the AI agent ecosystem, and that SentryAgent.ai implements this for free
### Requirement: Concepts guide explains the agent lifecycle
The guide SHALL explain the four lifecycle states of an agent (active, suspended, decommissioned) and what each state means for credential and token behaviour.
#### Scenario: Developer understands what happens when an agent is decommissioned
- **WHEN** the developer reads the lifecycle section
- **THEN** they SHALL understand that decommissioning is irreversible, all credentials are revoked, and no new tokens can be issued
### Requirement: Concepts guide explains OAuth 2.0 Client Credentials in plain English
The guide SHALL explain the Client Credentials grant in plain English — no RFC references, no formal OAuth jargon — focused on how agents use it to authenticate.
#### Scenario: Developer understands client_id and client_secret without prior OAuth knowledge
- **WHEN** the developer reads the OAuth section
- **THEN** they SHALL understand that client_id identifies the agent and client_secret proves it — analogous to a username and password for machines
### Requirement: Concepts guide explains the free-tier limits
The guide SHALL document all free-tier limits (100 agents, 10,000 tokens/month, 100 req/min, 90-day audit retention) in a clear table.
#### Scenario: Developer knows the limits before hitting them
- **WHEN** the developer reads the free-tier section
- **THEN** they SHALL see a table with all four limits and a note on what happens when each is exceeded

56
openspec/changes/bedroom-developer-docs/specs/developer-guides/spec.md Normal file
View File

@@ -0,0 +1,56 @@
## ADDED Requirements
### Requirement: Developer guides index exists at docs/developers/guides/README.md
The system SHALL provide a guides index at `docs/developers/guides/README.md` listing all available guides with one-line descriptions and links.
#### Scenario: Developer finds the right guide quickly
- **WHEN** the developer opens the guides folder
- **THEN** they SHALL see a list of all guides with descriptions so they can choose the one relevant to their task
### Requirement: Agent registration guide exists at docs/developers/guides/register-an-agent.md
The system SHALL provide a step-by-step guide for registering an agent, including all required and optional fields, validation rules, and how to handle the response.
#### Scenario: Developer registers their first agent
- **WHEN** the developer follows the registration guide
- **THEN** they SHALL successfully create an agent and understand what `agentId`, `clientId`, and `status` mean in the response
#### Scenario: Developer understands registration validation errors
- **WHEN** the guide covers validation
- **THEN** it SHALL show examples of common validation errors (missing required fields, invalid email format) and how to fix them
### Requirement: Credential management guide exists at docs/developers/guides/manage-credentials.md
The system SHALL provide a guide covering all four credential operations: generate, list, rotate, and revoke — with curl examples and explanation of when to use each.
#### Scenario: Developer rotates a compromised credential
- **WHEN** the developer follows the rotation section
- **THEN** they SHALL understand that rotation replaces the secret while keeping the same `credentialId`, and the old secret is immediately invalid
#### Scenario: Developer understands credential revocation vs agent decommission
- **WHEN** the developer reads the guide
- **THEN** they SHALL understand the difference: revoking a credential leaves the agent active with other credentials; decommissioning the agent revokes everything permanently
### Requirement: Token guide exists at docs/developers/guides/issue-and-revoke-tokens.md
The system SHALL provide a guide covering token issuance, introspection, and revocation — explaining the JWT structure, expiry, and how to use the Bearer token in API requests.
#### Scenario: Developer uses a token to authenticate a request
- **WHEN** the developer follows the token guide
- **THEN** they SHALL see an example of using the issued token as a Bearer token in an Authorization header on a subsequent API call
#### Scenario: Developer introspects a token to check validity
- **WHEN** the developer reads the introspection section
- **THEN** they SHALL understand what `active: true/false` means and what fields are returned
#### Scenario: Developer revokes a token
- **WHEN** the developer follows the revocation section
- **THEN** they SHALL understand that revoked tokens are immediately invalid even if not yet expired
### Requirement: Audit log guide exists at docs/developers/guides/query-audit-logs.md
The system SHALL provide a guide for querying the audit log — covering available filters (agentId, action, outcome, date range), pagination, and how to interpret audit events.
#### Scenario: Developer queries audit events for a specific agent
- **WHEN** the developer follows the audit guide
- **THEN** they SHALL see a curl example filtering by `agentId` and understand the structure of each audit event
#### Scenario: Developer understands audit log retention
- **WHEN** the developer reads the guide
- **THEN** they SHALL understand that free-tier audit logs are retained for 90 days and what happens after that window

45
openspec/changes/bedroom-developer-docs/specs/quick-start/spec.md Normal file
View File

@@ -0,0 +1,45 @@
## ADDED Requirements
### Requirement: Quick-start guide exists at docs/developers/quick-start.md
The system SHALL provide a quick-start guide at `docs/developers/quick-start.md` that enables a bedroom developer to register their first agent and issue an OAuth 2.0 access token in under 5 minutes.
#### Scenario: Developer completes quick-start from zero
- **WHEN** a developer with no prior AgentIdP knowledge follows the quick-start guide
- **THEN** they SHALL have a registered agent, a valid credential, and a working access token by the end
### Requirement: Quick-start lists exact prerequisites
The quick-start guide SHALL list all prerequisites at the top before any steps, so the developer knows what they need before starting.
#### Scenario: Prerequisites are minimal and explicit
- **WHEN** the developer reads the prerequisites section
- **THEN** they SHALL see exactly: Docker (for running PostgreSQL and Redis) and curl (for API calls) — nothing else required
### Requirement: Quick-start provides a working docker-compose startup command
The quick-start guide SHALL include a single command to start the required infrastructure (PostgreSQL + Redis) using the project's `docker-compose.yml`.
#### Scenario: Developer starts infrastructure
- **WHEN** the developer runs the provided docker-compose command
- **THEN** the guide SHALL confirm what services are started and what ports they run on
### Requirement: Quick-start covers the full 4-step workflow
The quick-start guide SHALL cover exactly these four steps in order, each with a working curl command and the expected response:
1. Start the AgentIdP server
2. Register an agent (`POST /agents`)
3. Generate a credential (`POST /agents/{agentId}/credentials`)
4. Issue an access token (`POST /token`)
#### Scenario: Each step has a copy-pasteable curl command
- **WHEN** the developer reads any step
- **THEN** they SHALL find a complete curl command with real placeholder values they can substitute
#### Scenario: Each step shows the expected JSON response
- **WHEN** the developer runs a curl command from the guide
- **THEN** the guide SHALL show them what a successful response looks like so they can verify their output
### Requirement: Quick-start ends with a next-steps section
The quick-start guide SHALL end with a "What's Next" section linking to: core-concepts.md, developer-guides.md, and api-reference.md.
#### Scenario: Developer knows where to go after quick-start
- **WHEN** the developer reaches the end of the quick-start
- **THEN** they SHALL see at least 3 links to deeper documentation

50
openspec/changes/bedroom-developer-docs/tasks.md Normal file
View File

@@ -0,0 +1,50 @@
## 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