sentryagent-idp/openspec/changes/archive/developer-docs-phase6-update/specs/ws3-quick-start/spec.md

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:

---

## 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):

{
  "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:

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:

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):

## 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:

## 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.