diff --git a/docs/getting-started/complete-workflow.md b/docs/getting-started/complete-workflow.md index 1ccc508..51dc3b0 100644 --- 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 index 66c6d9a..6361e2f 100644 --- 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 index f6cc955..5aa8250 100644 --- 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. ---