docs: commit all Phase 6 documentation updates and OpenSpec archives
- devops docs: 8 files updated for Phase 6 state; field-trial.md added (946-line runbook) - developer docs: api-reference (50+ endpoints), quick-start, 5 existing guides updated, 5 new guides added - engineering docs: all 12 files updated (services, architecture, SDK guide, testing, overview) - OpenSpec archives: phase-7-devops-field-trial, developer-docs-phase6-update, engineering-docs-phase6-update - VALIDATOR.md + scripts/start-validator.sh: V&V Architect tooling added - .gitignore: exclude session artifacts, build artifacts, and agent workspaces Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SentryAgent.ai Developer
@@ -0,0 +1,23 @@
|
||||
id: developer-docs-phase6-update
|
||||
title: "Developer Documentation — Phase 6 Complete Update"
|
||||
status: complete
|
||||
proposed: 2026-04-04
|
||||
approved: 2026-04-04
|
||||
approved-by: CEO
|
||||
completed: 2026-04-04
|
||||
workstreams:
|
||||
- id: WS1
|
||||
title: "Update api-reference.md — all current endpoints"
|
||||
status: complete
|
||||
- id: WS2
|
||||
title: "Update concepts.md — Phase 3–6 concepts"
|
||||
status: complete
|
||||
- id: WS3
|
||||
title: "Update quick-start.md — org creation prerequisite"
|
||||
status: complete
|
||||
- id: WS4
|
||||
title: "Update guides/ — revise existing + add Phase 3–6 guides"
|
||||
status: complete
|
||||
- id: WS5
|
||||
title: "Update README.md — fix typo, update index"
|
||||
status: complete
|
||||
@@ -0,0 +1,34 @@
|
||||
# OpenSpec Proposal — developer-docs-phase6-update
|
||||
|
||||
**Status:** Approved
|
||||
**Proposed:** 2026-04-04
|
||||
**Approved by:** CEO
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The developer documentation in `docs/developers/` was written during Phase 2. Phases 3–6 shipped
|
||||
analytics, API tiers, AGNTCY compliance, A2A delegation, DID identity, OIDC, webhooks, federation,
|
||||
and the marketplace — none of which appear in the developer docs. The API reference covers only
|
||||
14 endpoints; the current codebase has ~25+ endpoints. The README contains a "bedroom developers"
|
||||
typo. External developers cannot use Phase 3–6 features without documentation.
|
||||
|
||||
## Workstreams
|
||||
|
||||
### WS1 — api-reference.md
|
||||
Update to document all current endpoints with full request/response schemas, auth requirements,
|
||||
and error codes. Replace the 14-endpoint Phase 1 reference with the complete Phase 6 surface.
|
||||
|
||||
### WS2 — concepts.md
|
||||
Add Phase 3–6 concepts: multi-tenancy/organizations, DID identity (did:web), OIDC provider,
|
||||
A2A delegation, API tier plans (Free/Pro/Enterprise), and AGNTCY compliance.
|
||||
|
||||
### WS3 — quick-start.md
|
||||
Update to add org creation as Step 1 (now required before agent registration), and verify all
|
||||
endpoint paths match current routes.
|
||||
|
||||
### WS4 — guides/
|
||||
Revise the 4 existing guides for current endpoint paths and org-scoped requests.
|
||||
Add new guides: analytics dashboard, tier management, A2A delegation, webhooks, AGNTCY compliance.
|
||||
|
||||
### WS5 — README.md
|
||||
Fix "bedroom developers" typo → "developers". Update document index to list all new guides.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,283 @@
|
||||
# WS2 Spec — concepts.md
|
||||
|
||||
## Target file
|
||||
`docs/developers/concepts.md`
|
||||
|
||||
## Objective
|
||||
Add six new concept sections to the existing file. Do NOT modify any of the existing sections
|
||||
(What is AgentIdP?, What is an AI Agent Identity?, AGNTCY Alignment, Agent Lifecycle,
|
||||
OAuth 2.0 Client Credentials, Free Tier Limits). Append the new sections at the end of the file,
|
||||
each separated by a `---` horizontal rule and preceded by a level-2 heading.
|
||||
|
||||
---
|
||||
|
||||
## New section order (append after existing content)
|
||||
|
||||
1. Organizations and Multi-tenancy
|
||||
2. DID Identity
|
||||
3. OIDC Provider
|
||||
4. A2A Delegation
|
||||
5. API Tier Plans
|
||||
6. AGNTCY Compliance
|
||||
|
||||
---
|
||||
|
||||
## Section 1 — Organizations and Multi-tenancy
|
||||
|
||||
**Heading**: `## Organizations and Multi-tenancy`
|
||||
|
||||
**Content to write** (3 paragraphs + table):
|
||||
|
||||
Paragraph 1:
|
||||
An **organization** is the top-level grouping unit in AgentIdP. Every registered agent can be
|
||||
scoped to an organization by including an `organization_id` in the agent registration request.
|
||||
Organizations have a unique `slug` (URL-safe identifier), a display `name`, and a `planTier`
|
||||
that controls per-org resource limits. All API operations that involve analytics, webhooks, tiers,
|
||||
and delegation are tenant-scoped: they only see data belonging to their organization.
|
||||
|
||||
Paragraph 2:
|
||||
**Tenant isolation** is enforced at the service layer. Every query involving multi-tenant data
|
||||
filters by `organization_id`. A token issued to an agent in org A cannot read data from org B.
|
||||
The `organization_id` is embedded in the JWT at token issuance time and validated on every
|
||||
request. This means you do not need to pass an org ID as a query parameter — it is derived
|
||||
automatically from the authenticated token.
|
||||
|
||||
Paragraph 3:
|
||||
When you create an organization, you define its `slug`. Slugs are immutable — once set, they
|
||||
cannot be changed. Choose a slug that matches your domain or product namespace, as it is used
|
||||
in DID identifiers for agents in that organization. Membership is managed through the
|
||||
`POST /api/v1/organizations/{orgId}/members` endpoint, which lets you add an existing agent
|
||||
to an organization with a `member` or `admin` role.
|
||||
|
||||
Table — org field reference:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `organizationId` | UUID | System-assigned immutable identifier |
|
||||
| `name` | string | Human-readable display name |
|
||||
| `slug` | string | URL-safe unique identifier (immutable after creation) |
|
||||
| `planTier` | enum | `free` \| `pro` \| `enterprise` |
|
||||
| `maxAgents` | integer | Maximum active agents in this org |
|
||||
| `maxTokensPerMonth` | integer | Maximum token issuances per month |
|
||||
| `status` | enum | `active` \| `suspended` \| `deleted` |
|
||||
|
||||
---
|
||||
|
||||
## Section 2 — DID Identity
|
||||
|
||||
**Heading**: `## DID Identity`
|
||||
|
||||
**Content to write** (3 paragraphs + DID structure example):
|
||||
|
||||
Paragraph 1:
|
||||
Every agent registered in AgentIdP automatically receives a **Decentralized Identifier (DID)**
|
||||
using the `did:web` method. A DID is a globally unique, self-describing identifier that does not
|
||||
rely on a central registry. The DID for an agent takes the form
|
||||
`did:web:<host>:agents:<agentId>` — for example,
|
||||
`did:web:localhost%3A3000:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890`. The `did:web` method
|
||||
means the DID document is resolvable via HTTPS: a resolver fetches
|
||||
`https://<host>/api/v1/agents/<agentId>/did`.
|
||||
|
||||
Paragraph 2:
|
||||
The **DID Document** is a JSON-LD object that describes the agent's cryptographic keys and
|
||||
service endpoints. It contains: the agent's DID as its `id`, a `verificationMethod` array with
|
||||
the agent's public key in JWK format, an `authentication` array referencing that key, and an
|
||||
`agntcy` extension object carrying agent metadata (type, capabilities, version, owner,
|
||||
deploymentEnv). This document is publicly accessible — no authentication required — so any
|
||||
external system can verify this agent's identity without contacting AgentIdP directly.
|
||||
|
||||
Paragraph 3:
|
||||
The `did:web` scheme was chosen because it is widely supported by DID resolvers, requires no
|
||||
blockchain, and leverages standard HTTPS infrastructure. When an external system receives a
|
||||
token from your agent, it can resolve your agent's DID, retrieve the public key from the DID
|
||||
Document, and independently verify the token's signature. This is the foundation of
|
||||
cross-system agent identity verification.
|
||||
|
||||
DID document structure diagram (Markdown code block):
|
||||
|
||||
```
|
||||
DID Document structure for a registered agent
|
||||
───────────────────────────────────────────────
|
||||
{
|
||||
"@context": ["https://www.w3.org/ns/did/v1"],
|
||||
"id": "did:web:<host>:agents:<agentId>",
|
||||
"controller": "did:web:<host>:agents:<agentId>",
|
||||
"verificationMethod": [
|
||||
{
|
||||
"id": "<did>#key-1",
|
||||
"type": "JsonWebKey2020",
|
||||
"controller": "<did>",
|
||||
"publicKeyJwk": { "kty": "RSA", ... }
|
||||
}
|
||||
],
|
||||
"authentication": ["<did>#key-1"],
|
||||
"agntcy": {
|
||||
"agentId": "<uuid>",
|
||||
"agentType": "screener",
|
||||
"capabilities": ["resume:read"],
|
||||
"deploymentEnv": "production",
|
||||
"owner": "talent-team",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 3 — OIDC Provider
|
||||
|
||||
**Heading**: `## OIDC Provider`
|
||||
|
||||
**Content to write** (3 paragraphs):
|
||||
|
||||
Paragraph 1:
|
||||
AgentIdP implements a subset of the **OpenID Connect (OIDC)** protocol, acting as an OIDC
|
||||
Provider for the agents it manages. This means AgentIdP publishes a standard discovery
|
||||
document at `GET /.well-known/openid-configuration`, which any OIDC-aware client can use to
|
||||
discover supported grant types, token endpoint, JWKS URI, and other metadata. It also exposes
|
||||
a JWKS endpoint at `GET /.well-known/jwks.json` for external systems to retrieve the public
|
||||
keys used to verify tokens.
|
||||
|
||||
Paragraph 2:
|
||||
The **`/agent-info` endpoint** is the equivalent of OIDC's UserInfo endpoint — it returns
|
||||
identity claims for the authenticated agent. External systems that receive a token issued by
|
||||
AgentIdP can call this endpoint (with that token) to retrieve the agent's verified identity
|
||||
attributes: its `agentId`, `email`, `agentType`, `capabilities`, and `organization_id`. This
|
||||
is particularly useful when a downstream service needs to verify the identity of an agent
|
||||
presenting a token, without duplicating identity data in its own store.
|
||||
|
||||
Paragraph 3:
|
||||
AgentIdP also supports **OIDC token exchange for GitHub Actions**. If you run your agent
|
||||
deployment workflows in GitHub Actions, you can configure a trust policy
|
||||
(`POST /api/v1/oidc/trust-policies`) that maps a GitHub repository and branch to an AgentIdP
|
||||
agent. The workflow can then exchange its GitHub OIDC JWT for an AgentIdP access token via
|
||||
`POST /api/v1/oidc/token` — no stored secrets required. This enables keyless, short-lived
|
||||
token issuance in CI/CD pipelines.
|
||||
|
||||
---
|
||||
|
||||
## Section 4 — A2A Delegation
|
||||
|
||||
**Heading**: `## A2A Delegation`
|
||||
|
||||
**Content to write** (3 paragraphs + flow diagram):
|
||||
|
||||
Paragraph 1:
|
||||
**Agent-to-Agent (A2A) delegation** allows one agent to grant another agent a subset of its own
|
||||
OAuth 2.0 scopes for a limited time. This is the building block for multi-agent pipelines where
|
||||
an orchestrator agent needs to delegate work to a specialist sub-agent without sharing its own
|
||||
full credentials. A delegation chain consists of: a delegator (the agent granting authority),
|
||||
a delegatee (the agent receiving authority), a set of scopes (must be a strict subset of the
|
||||
delegator's own scopes), and a TTL (60 seconds to 86,400 seconds).
|
||||
|
||||
Paragraph 2:
|
||||
The **grant flow** is straightforward: the delegator calls `POST /api/v1/oauth2/token/delegate`
|
||||
with the delegatee's agent ID, the scopes to grant, and the TTL. AgentIdP returns a signed
|
||||
delegation token. The delegatee presents this token when calling
|
||||
`POST /api/v1/oauth2/token/verify-delegation` to prove it has been granted authority. AgentIdP
|
||||
verifies the chain integrity and returns the delegation details including whether it is still
|
||||
valid. The delegator can revoke the chain at any time via
|
||||
`DELETE /api/v1/oauth2/token/delegate/{chainId}`.
|
||||
|
||||
Paragraph 3:
|
||||
Delegation is useful for: workflow handoffs between specialist agents, granting a monitoring
|
||||
agent read-only access to resources owned by a processing agent, and time-limited cross-agent
|
||||
authorization without credential sharing. Because delegation tokens are signed and verified
|
||||
server-side, a delegatee cannot extend the TTL, expand the scope, or pass the delegation to a
|
||||
third agent. The chain is always exactly two hops: delegator → delegatee.
|
||||
|
||||
Delegation flow (Markdown code block):
|
||||
|
||||
```
|
||||
A2A Delegation Flow
|
||||
───────────────────
|
||||
1. Orchestrator (delegator) calls POST /api/v1/oauth2/token/delegate
|
||||
→ body: { delegateeAgentId, scopes: ["agents:read"], ttlSeconds: 3600 }
|
||||
← response: { delegationToken: "...", chainId: "...", expiresAt: "..." }
|
||||
|
||||
2. Orchestrator passes delegationToken to the sub-agent out-of-band
|
||||
|
||||
3. Sub-agent (delegatee) calls POST /api/v1/oauth2/token/verify-delegation
|
||||
→ body: { delegationToken: "..." }
|
||||
← response: { valid: true, scopes: ["agents:read"], expiresAt: "..." }
|
||||
|
||||
4. Sub-agent uses its own Bearer token + confirmed scope to act on behalf
|
||||
|
||||
5. (Optional) Orchestrator calls DELETE /api/v1/oauth2/token/delegate/{chainId}
|
||||
to revoke early
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 5 — API Tier Plans
|
||||
|
||||
**Heading**: `## API Tier Plans`
|
||||
|
||||
**Content to write** (3 paragraphs + table):
|
||||
|
||||
Paragraph 1:
|
||||
AgentIdP has three subscription tiers: **Free**, **Pro**, and **Enterprise**. Every organization
|
||||
is on one tier at a time. The tier determines the resource limits enforced at runtime: maximum
|
||||
number of active agents, maximum API calls per day, and maximum token issuances per day. When a
|
||||
limit is reached, the relevant operation returns a `403 FREE_TIER_LIMIT_EXCEEDED` error until the
|
||||
next calendar day resets the counter (for daily limits) or until you upgrade your tier.
|
||||
|
||||
Paragraph 2:
|
||||
You can check your current tier, configured limits, and live usage at any time by calling
|
||||
`GET /api/v1/tiers/status`. The response shows your tier name, all three limit values, and the
|
||||
live usage counters for the current day. If you need higher limits, call
|
||||
`POST /api/v1/tiers/upgrade` with `{ "target_tier": "pro" }` or `"enterprise"`. This creates a
|
||||
Stripe Checkout Session and returns a one-time `checkoutUrl`. After payment, the organization's
|
||||
tier is updated automatically via Stripe webhook.
|
||||
|
||||
Paragraph 3:
|
||||
Enterprise tier limits are effectively unlimited (enforced as `Infinity` in the tier
|
||||
configuration). Enterprise customers should contact SentryAgent.ai to arrange billing and
|
||||
configure custom limits if needed. The `maxAgents` and `maxTokensPerMonth` fields on an
|
||||
organization record can be overridden at org creation or update to set tighter or looser limits
|
||||
than the tier defaults, regardless of tier.
|
||||
|
||||
Tier comparison table:
|
||||
|
||||
| Limit | Free | Pro | Enterprise |
|
||||
|-------|------|-----|------------|
|
||||
| Max agents | 10 | 100 | Unlimited |
|
||||
| Max API calls / day | 1,000 | 50,000 | Unlimited |
|
||||
| Max token issuances / day | 1,000 | 50,000 | Unlimited |
|
||||
| Audit log retention | 90 days | 90 days | 90 days |
|
||||
| Webhooks | Yes | Yes | Yes |
|
||||
| Analytics | Yes | Yes | Yes |
|
||||
| A2A Delegation | Yes | Yes | Yes |
|
||||
|
||||
---
|
||||
|
||||
## Section 6 — AGNTCY Compliance
|
||||
|
||||
**Heading**: `## AGNTCY Compliance`
|
||||
|
||||
**Content to write** (3 paragraphs):
|
||||
|
||||
Paragraph 1:
|
||||
**AGNTCY** is an open standard from the Linux Foundation that defines how AI agents should be
|
||||
identified, described, and governed across platforms. AgentIdP implements AGNTCY compliance
|
||||
in two ways: every agent automatically gets a DID and an agent card (a structured JSON object
|
||||
that describes the agent in the AGNTCY format), and AgentIdP can generate a **compliance
|
||||
report** that summarizes the verified state of all agents in a tenant. An agent card is the
|
||||
AGNTCY equivalent of a business card — it carries the agent's DID, type, capabilities, owner,
|
||||
version, and identity provider.
|
||||
|
||||
Paragraph 2:
|
||||
The **compliance report** (available at `GET /api/v1/compliance/report`) covers two dimensions:
|
||||
agent-identity verification (are all active agents reachable via their DID?) and audit-trail
|
||||
integrity (is the hash chain of audit events intact?). The report includes a boolean
|
||||
`agntcyConformance` field that summarizes whether the tenant meets AGNTCY baseline requirements.
|
||||
Reports are cached in Redis for 5 minutes; the `X-Cache: HIT` header signals a cached response.
|
||||
|
||||
Paragraph 3:
|
||||
For self-auditing and external audits, you can export all active agents as AGNTCY agent cards
|
||||
in bulk via `GET /api/v1/compliance/agent-cards`. This is an array of card objects that
|
||||
external compliance tools and AGNTCY-compatible registries can ingest directly. The
|
||||
`GET /api/v1/compliance/controls` endpoint (no authentication required) provides a live
|
||||
status snapshot of all SOC 2 Trust Services Criteria controls that AgentIdP monitors internally.
|
||||
These endpoints are gated by the `COMPLIANCE_ENABLED` environment variable; if disabled, they
|
||||
return `404`.
|
||||
@@ -0,0 +1,212 @@
|
||||
# WS3 Spec — quick-start.md
|
||||
|
||||
## Target file
|
||||
`docs/developers/quick-start.md`
|
||||
|
||||
## Objective
|
||||
The quick start must be updated so that creating an organization becomes Step 1, since agents
|
||||
can now be scoped to an organization. All steps are renumbered accordingly. All endpoint paths
|
||||
must be verified against current routes. The new step order is:
|
||||
|
||||
1. Clone and configure (unchanged)
|
||||
2. Start infrastructure (unchanged)
|
||||
3. Start the AgentIdP server (unchanged)
|
||||
4. Generate a bootstrap token (unchanged)
|
||||
5. **[NEW]** Create an organization
|
||||
6. Register an agent (update to include `organization_id`)
|
||||
7. Generate a credential (renumbered, content unchanged)
|
||||
8. Issue an access token (renumbered, content unchanged)
|
||||
|
||||
The "What's next" section at the bottom must be updated to include new guides.
|
||||
|
||||
---
|
||||
|
||||
## Surgical edits — exact changes to make
|
||||
|
||||
### Edit 1 — Update the title paragraph
|
||||
|
||||
**Find** (exact text):
|
||||
```
|
||||
This guide gets you from zero to a working agent identity with a valid OAuth 2.0 access token. It takes under 5 minutes.
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```
|
||||
This guide gets you from zero to a working agent identity inside an organization, with a valid OAuth 2.0 access token. It takes under 5 minutes.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edit 2 — Renumber Step 4 and insert new Step 5
|
||||
|
||||
After the existing Step 4 section (Generate a bootstrap token), which ends with:
|
||||
|
||||
```
|
||||
> This bootstrap token is a one-time tool for registering your first agent. Once you have an agent with credentials, use `POST /token` for all subsequent authentication.
|
||||
```
|
||||
|
||||
Insert a `---` separator followed by the new **Step 5 — Create an organization** section:
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
## Step 5 — Create an organization
|
||||
|
||||
Agents are scoped to organizations. Create one now so your agent has an `organization_id` to belong to:
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://localhost:3000/api/v1/organizations \
|
||||
-H "Authorization: Bearer $BOOTSTRAP_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "My AI Project",
|
||||
"slug": "my-ai-project"
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
Example response (`201 Created`):
|
||||
|
||||
```json
|
||||
{
|
||||
"organizationId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
|
||||
"name": "My AI Project",
|
||||
"slug": "my-ai-project",
|
||||
"planTier": "free",
|
||||
"maxAgents": 10,
|
||||
"maxTokensPerMonth": 10000,
|
||||
"status": "active",
|
||||
"createdAt": "2026-04-04T09:00:00.000Z",
|
||||
"updatedAt": "2026-04-04T09:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
Save the `organizationId`:
|
||||
|
||||
```bash
|
||||
export ORG_ID="org-0a1b2c3d-e4f5-6789-abcd-ef0123456789"
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edit 3 — Renumber the agent registration step
|
||||
|
||||
**Find** (heading only):
|
||||
```
|
||||
## Step 5 — Register an agent
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```
|
||||
## Step 6 — Register an agent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edit 4 — Update the agent registration curl command to include organization_id
|
||||
|
||||
**Find** (exact curl command):
|
||||
```bash
|
||||
curl -s -X POST http://localhost:3000/api/v1/agents \
|
||||
-H "Authorization: Bearer $BOOTSTRAP_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "my-first-agent@myproject.ai",
|
||||
"agentType": "custom",
|
||||
"version": "1.0.0",
|
||||
"capabilities": ["data:read"],
|
||||
"owner": "my-team",
|
||||
"deploymentEnv": "development"
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```bash
|
||||
curl -s -X POST http://localhost:3000/api/v1/agents \
|
||||
-H "Authorization: Bearer $BOOTSTRAP_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "my-first-agent@myproject.ai",
|
||||
"agentType": "custom",
|
||||
"version": "1.0.0",
|
||||
"capabilities": ["data:read"],
|
||||
"owner": "my-team",
|
||||
"deploymentEnv": "development",
|
||||
"organization_id": "'$ORG_ID'"
|
||||
}' | jq .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edit 5 — Renumber Step 6 (credential generation)
|
||||
|
||||
**Find** (heading only):
|
||||
```
|
||||
## Step 6 — Generate a credential
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```
|
||||
## Step 7 — Generate a credential
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edit 6 — Renumber Step 7 (token issuance)
|
||||
|
||||
**Find** (heading only):
|
||||
```
|
||||
## Step 7 — Issue an access token
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```
|
||||
## Step 8 — Issue an access token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edit 7 — Update the "What's next" section
|
||||
|
||||
**Find** (entire What's next section):
|
||||
```markdown
|
||||
## What's next
|
||||
|
||||
- [Core Concepts](concepts.md) — understand AgentIdP, AGNTCY, and the agent identity model
|
||||
- [Guides](guides/README.md) — step-by-step walkthroughs for credentials, tokens, and audit logs
|
||||
- [API Reference](api-reference.md) — every endpoint documented with curl examples
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```markdown
|
||||
## What's next
|
||||
|
||||
- [Core Concepts](concepts.md) — understand AgentIdP, AGNTCY, orgs, DID, delegation, and tiers
|
||||
- [Guides](guides/README.md) — step-by-step walkthroughs for all workflows
|
||||
- [API Reference](api-reference.md) — every endpoint documented with curl examples
|
||||
|
||||
**New guides for Phase 6 features:**
|
||||
|
||||
- [Use the Analytics Dashboard](guides/use-analytics-dashboard.md) — query token trends and activity
|
||||
- [Manage API Tiers](guides/manage-api-tiers.md) — check limits and upgrade your plan
|
||||
- [A2A Delegation](guides/a2a-delegation.md) — delegate authority between agents
|
||||
- [Configure Webhooks](guides/configure-webhooks.md) — subscribe to real-time events
|
||||
- [AGNTCY Compliance](guides/agntcy-compliance.md) — export agent cards and generate compliance reports
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification checklist
|
||||
|
||||
The Developer must verify all curl paths in the updated file match these current routes:
|
||||
|
||||
| Action | Current endpoint |
|
||||
|--------|-----------------|
|
||||
| Create org | `POST /api/v1/organizations` |
|
||||
| Register agent | `POST /api/v1/agents` |
|
||||
| Generate credential | `POST /api/v1/agents/{agentId}/credentials` |
|
||||
| Issue token | `POST /api/v1/token` |
|
||||
|
||||
The bootstrap token scopes must include `agents:write` and `organizations:write` (or the equivalent
|
||||
OPA-enforced policy). The bootstrap token generation node script in Step 4 currently uses
|
||||
`agents:read agents:write tokens:read audit:read`. This is unchanged — no edit needed there.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,77 @@
|
||||
# WS5 Spec — README.md
|
||||
|
||||
## Target file
|
||||
`docs/developers/README.md`
|
||||
|
||||
## Objective
|
||||
Two surgical edits to the existing file:
|
||||
1. Fix the "bedroom developers" typo in line 3.
|
||||
2. Expand the Guides table to list all 9 guides (4 existing + 5 new).
|
||||
|
||||
---
|
||||
|
||||
## Edit 1 — Fix typo in the opening paragraph
|
||||
|
||||
**Location**: Line 3 of the file (the subtitle/description line).
|
||||
|
||||
**Find** (exact text):
|
||||
```
|
||||
The complete documentation for bedroom developers building with SentryAgent.ai AgentIdP.
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```
|
||||
The complete documentation for developers building with SentryAgent.ai AgentIdP.
|
||||
```
|
||||
|
||||
No other changes to this paragraph.
|
||||
|
||||
---
|
||||
|
||||
## Edit 2 — Expand the Guides table
|
||||
|
||||
**Find** (the entire Guides section, from heading to end of table):
|
||||
```markdown
|
||||
## Guides
|
||||
|
||||
| Guide | What it covers |
|
||||
|-------|----------------|
|
||||
| [Register an Agent](guides/register-an-agent.md) | All fields, validation rules, common errors |
|
||||
| [Manage Credentials](guides/manage-credentials.md) | Generate, list, rotate, revoke credentials |
|
||||
| [Issue and Revoke Tokens](guides/issue-and-revoke-tokens.md) | OAuth 2.0 client credentials flow, introspect, revoke |
|
||||
| [Query Audit Logs](guides/query-audit-logs.md) | Filters, pagination, event structure, retention |
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```markdown
|
||||
## Guides
|
||||
|
||||
| Guide | What it covers |
|
||||
|-------|----------------|
|
||||
| [Register an Agent](guides/register-an-agent.md) | All fields, org scoping, validation rules, common errors |
|
||||
| [Manage Credentials](guides/manage-credentials.md) | Generate, list, rotate, revoke credentials |
|
||||
| [Issue and Revoke Tokens](guides/issue-and-revoke-tokens.md) | OAuth 2.0 client credentials flow, introspect, revoke |
|
||||
| [Query Audit Logs](guides/query-audit-logs.md) | Filters, pagination, event structure, retention |
|
||||
| [Use the Analytics Dashboard](guides/use-analytics-dashboard.md) | Query token trends, activity heatmap, per-agent usage |
|
||||
| [Manage API Tiers](guides/manage-api-tiers.md) | Check current tier, understand limits, trigger upgrade |
|
||||
| [A2A Delegation](guides/a2a-delegation.md) | Create and verify agent-to-agent delegation chains |
|
||||
| [Configure Webhooks](guides/configure-webhooks.md) | Subscribe to events, delivery guarantees, inspect history |
|
||||
| [AGNTCY Compliance](guides/agntcy-compliance.md) | Export agent cards, generate compliance reports, verify audit chain |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification checklist
|
||||
|
||||
After both edits:
|
||||
- Line 3 must read: `The complete documentation for developers building with SentryAgent.ai AgentIdP.`
|
||||
- The Documents table (the first table in the file, listing Quick Start / Core Concepts / Guides / API Reference) is unchanged.
|
||||
- The Guides table has exactly 9 rows.
|
||||
- All guide filenames match exactly the files that WS4 will create:
|
||||
- `guides/use-analytics-dashboard.md`
|
||||
- `guides/manage-api-tiers.md`
|
||||
- `guides/a2a-delegation.md`
|
||||
- `guides/configure-webhooks.md`
|
||||
- `guides/agntcy-compliance.md`
|
||||
- The Free Tier Limits table at the bottom of the file is unchanged.
|
||||
- The Base URL section is unchanged.
|
||||
Reference in New Issue
Block a user