sentryagent-idp/openspec/specs/developer-guides/spec.md at 0fad328329934016dc0e15132d7bc89c2c228521

Files

SentryAgent.ai Developer f1fbe0e29a chore(openspec): archive all completed changes, sync 14 new specs to library

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>

2026-04-02 03:50:47 +00:00

3.6 KiB

Raw Blame History

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

3.6 KiB Raw Blame History