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

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