capiscio · beonde · May 2, 2026 · May 2, 2026
diff --git a/docs/getting-started/complete-workflow.md b/docs/getting-started/complete-workflow.md
@@ -185,7 +185,7 @@ export CAPISCIO_API_KEY="sk_live_xxx"
 ### 3.4 Register Your Agent
 
 ```bash
-curl -X POST http://localhost:8080/v1/agents \
+curl -X POST http://localhost:8080/v1/sdk/agents \
   -H "X-Capiscio-Registry-Key: $CAPISCIO_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -224,27 +224,34 @@ _capiscio.my-agent.example.com TXT "capiscio-verification=550e8400-e29b-41d4-a71
 
 ### 4.2 Request Badge
 
+Use the CLI to request a badge (handles authentication automatically):
+
 ```bash
-curl -X POST "http://localhost:8080/v1/agents/$AGENT_ID/badge" \
-  -H "X-Capiscio-Registry-Key: $CAPISCIO_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "domain": "my-agent.example.com",
-    "trustLevel": "2"
-  }'
+capiscio badge keep \
+  --ca "http://localhost:8080" \
+  --agent-id "$AGENT_ID" \
+  --api-key "$CAPISCIO_API_KEY" \
+  --domain "my-agent.example.com" \
+  --level 2 \
+  --out ./badge.jwt
 ```
 
-Response:
+!!! note "SDK vs Dashboard Routes"
+    For programmatic badge issuance, use the CLI or Python SDK (which handle the [PoP flow](../reference/server/badge-ca.md#ial-1-proof-of-possession-rfc-003) automatically). The `/v1/agents/{id}/badge` REST endpoint is for the web dashboard only (Clerk JWT auth).
 
-```json
-{
-  "success": true,
-  "data": {
-    "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
-    "trustLevel": "2",
-    "expiresAt": "2025-01-15T10:35:00Z"
-  }
-}
+Verify the badge was issued:
+
+```bash
+capiscio badge verify ./badge.jwt
+```
+
+Output:
+
+```
+✓ Badge valid
+  Subject: did:web:registry.capisc.io:agents:550e8400
+  Level:   2 (DV)
+  Expires: 2025-01-15T10:35:00Z
 ```
 
 ### 4.3 Use Badge Keeper for Auto-Renewal

diff --git a/docs/reference/server/badge-ca.md b/docs/reference/server/badge-ca.md
@@ -72,11 +72,15 @@ The CA supports two badge issuance modes:
 
 ### IAL-0: Account-Based Issuance
 
-Simple badge issuance based on API key authentication. Suitable for internal systems where the caller controls the agent.
+Simple badge issuance based on account ownership. Available through the **dashboard API** (Clerk JWT auth) or via the SDK using the PoP-equivalent flow.
+
+!!! note "Route Authentication"
+    The IAL-0 endpoint `/v1/agents/{id}/badge` requires **Clerk JWT** (dashboard auth). For programmatic badge issuance from CLI/SDK, use the IAL-1 PoP flow via `/v1/sdk/agents/{did}/badge/challenge` + `/v1/sdk/agents/{did}/badge/pop`.
 
 ```bash
-curl -X POST https://registry.capisc.io/v1/agents/{did}/badge \
-  -H "X-Capiscio-Registry-Key: cpsc_live_xxx" \
+# Dashboard route (Clerk JWT - used by capiscio-ui)
+curl -X POST https://registry.capisc.io/v1/agents/{id}/badge \
+  -H "Authorization: Bearer YOUR_CLERK_JWT" \
   -H "Content-Type: application/json" \
   -d '{
     "mode": "ial0",
@@ -109,7 +113,7 @@ Two-phase challenge-response protocol that cryptographically proves the agent po
 **Phase 1: Request Challenge**
 
 ```bash
-curl -X POST https://registry.capisc.io/v1/agents/{did}/badge/challenge \
+curl -X POST https://registry.capisc.io/v1/sdk/agents/{did}/badge/challenge \
   -H "X-Capiscio-Registry-Key: cpsc_live_xxx" \
   -H "Content-Type: application/json" \
   -d '{
@@ -153,7 +157,7 @@ The agent creates a proof JWS signed with their private key:
 Then submit the proof:
 
 ```bash
-curl -X POST https://registry.capisc.io/v1/agents/{did}/badge/pop \
+curl -X POST https://registry.capisc.io/v1/sdk/agents/{did}/badge/pop \
   -H "Content-Type: application/json" \
   -d '{
     "challenge_id": "ch-550e8400-e29b-41d4-a716-446655440000",

diff --git a/docs/reference/server/index.md b/docs/reference/server/index.md
@@ -70,63 +70,72 @@ capiscio-server provides:
 
 ## API Endpoints Summary
 
-### Agents
+!!! note "Dual-Path Architecture"
+    capiscio-server has **two** endpoint groups for agent management — SDK routes (for programmatic access) and Dashboard routes (for the web UI). See [API Reference](api.md) for full details.
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/v1/agents` | List all agents |
-| `POST` | `/v1/agents` | Create new agent |
-| `GET` | `/v1/agents/{id}` | Get agent details |
-| `PUT` | `/v1/agents/{id}` | Update agent |
-| `DELETE` | `/v1/agents/{id}` | Delete agent |
-| `POST` | `/v1/agents/{id}/disable` | Disable agent |
-| `POST` | `/v1/agents/{id}/enable` | Enable agent |
+### SDK/CLI Routes (`X-Capiscio-Registry-Key`)
 
-### Badges
+Use these routes from the CLI, Python SDK, or CI/CD pipelines:
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `POST` | `/v1/agents/{id}/badge` | Issue badge for agent |
-| `POST` | `/v1/validate` | Verify a badge token |
-| `GET` | `/.well-known/jwks.json` | Get CA public keys (JWKS) |
-
-### DID Resolution
+| `GET` | `/v1/sdk/agents` | List agents |
+| `POST` | `/v1/sdk/agents` | Create agent |
+| `GET` | `/v1/sdk/agents/{id}` | Get agent details |
+| `PUT` | `/v1/sdk/agents/{id}` | Update agent |
+| `POST` | `/v1/sdk/agents/{did}/badge/challenge` | PoP challenge (RFC-003) |
+| `POST` | `/v1/sdk/agents/{did}/badge/pop` | PoP badge issuance |
+| `GET` | `/v1/sdk/servers` | List MCP servers (RFC-007) |
+| `POST` | `/v1/sdk/servers` | Register MCP server |
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/agents/{id}/did.json` | Get agent's DID document |
+### Dashboard Routes (Clerk JWT)
 
-### API Keys
+Used by the capiscio-ui web dashboard only:
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
+| `GET` | `/v1/agents` | List all agents |
+| `POST` | `/v1/agents` | Create new agent |
+| `POST` | `/v1/agents/{id}/badge` | Issue IAL-0 badge |
+| `POST` | `/v1/agents/{id}/disable` | Disable agent |
 | `GET` | `/v1/api-keys` | List API keys |
 | `POST` | `/v1/api-keys` | Create new API key |
 | `DELETE` | `/v1/api-keys/{id}` | Delete API key |
 
+### Public Endpoints (No Auth)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/v1/validate` | Verify a badge token |
+| `GET` | `/.well-known/jwks.json` | Get CA public keys (JWKS) |
+| `GET` | `/agents/{id}/did.json` | Get agent's DID document |
+| `GET` | `/servers/{id}/did.json` | Get MCP server's DID document |
+| `GET` | `/v1/badges/{jti}/status` | Badge revocation status |
+| `GET` | `/v1/agents/{id}/status` | Agent status |
+
 ---
 
 ## Authentication
 
-capiscio-server supports two authentication methods:
+capiscio-server supports two authentication methods depending on the route group:
 
-### API Key Authentication
+### API Key Authentication (SDK/CLI Routes)
 
-For programmatic access (agents, CI/CD), use the `X-Capiscio-Registry-Key` header:
+For programmatic access via `/v1/sdk/*` endpoints, use the `X-Capiscio-Registry-Key` header:
 
 ```bash
-curl -X POST https://registry.capisc.io/v1/agents/{id}/badge \
+curl -X POST https://registry.capisc.io/v1/sdk/agents \
   -H "X-Capiscio-Registry-Key: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{"domain": "my-agent.example.com", "trustLevel": "2"}'
+  -d '{"name": "my-agent", "domain": "my-agent.example.com"}'
 ```
 
 !!! note "Header Name"
     Use `X-Capiscio-Registry-Key` for API key authentication, not `Authorization: Bearer`. The `X-Capiscio-Badge` header is used for agent-to-agent badge transport (RFC-002 §9.1).
 
-### Clerk Authentication
+### Clerk Authentication (Dashboard Routes)
 
-For the web dashboard (capiscio-ui), authentication is handled via [Clerk](https://clerk.dev).
+For the web dashboard (capiscio-ui), authentication is handled via [Clerk](https://clerk.dev). Dashboard routes at `/v1/agents`, `/v1/api-keys`, etc. use Clerk JWTs.
 
 ---