API & MCP Testing

This page provides ready-to-run curl commands for every area of the 1claw API and MCP server. Use these to verify your deployment, debug integrations, or explore the API interactively.

Setup

Set these environment variables before running the examples:

export API="https://api.1claw.xyz"

1. Health checks (no auth required)

# Service health
curl -s "$API/v1/health" | python3 -m json.tool

# HSM connectivity
curl -s "$API/v1/health/hsm" | python3 -m json.tool

Expected: { "status": "ok" } for both.

2. Authentication

curl -s -X POST "$API/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"YourSecurePassword123!"}' \
  | python3 -m json.tool

curl -s -X POST "$API/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"YourSecurePassword123!"}' \
  | python3 -m json.tool

Save the access_token:

export TOKEN=$(curl -s -X POST "$API/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

curl -s -X POST "$API/v1/auth/google" \
  -H "Content-Type: application/json" \
  -d '{"id_token":"<google-id-token>"}' \
  | python3 -m json.tool

Refresh token

curl -s -X POST "$API/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<refresh_token>"}' \
  | python3 -m json.tool

Revoke token

curl -s -X DELETE "$API/v1/auth/token" \
  -H "Authorization: Bearer $TOKEN"

Change password

curl -s -X POST "$API/v1/auth/change-password" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"old","new_password":"new"}' \
  | python3 -m json.tool

3. Personal API Keys

# Create an API key
curl -s -X POST "$API/v1/auth/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-ci-key"}' \
  | python3 -m json.tool

# List API keys
curl -s "$API/v1/auth/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Exchange API key for JWT
curl -s -X POST "$API/v1/auth/api-key-token" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"1claw_..."}' \
  | python3 -m json.tool

# Revoke an API key
curl -s -X DELETE "$API/v1/auth/api-keys/<key_id>" \
  -H "Authorization: Bearer $TOKEN"

4. Vaults

# Create vault
curl -s -X POST "$API/v1/vaults" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"test-vault","description":"Testing"}' \
  | python3 -m json.tool

# List vaults
curl -s "$API/v1/vaults" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Get a specific vault
export VAULT_ID="<vault-id-from-create>"
curl -s "$API/v1/vaults/$VAULT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Delete vault
curl -s -X DELETE "$API/v1/vaults/$VAULT_ID" \
  -H "Authorization: Bearer $TOKEN"

5. Secrets

# Store a secret (PUT creates or updates)
curl -s -X PUT "$API/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "api_key",
    "value": "sk-proj-test123",
    "metadata": {"env": "test"}
  }' \
  | python3 -m json.tool

# List secrets (metadata only, no values)
curl -s "$API/v1/vaults/$VAULT_ID/secrets" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Get secret value (decrypted)
curl -s "$API/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Store a nested-path secret
curl -s -X PUT "$API/v1/vaults/$VAULT_ID/secrets/config/prod/database" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"password","value":"postgres://..."}' \
  | python3 -m json.tool

# Delete a secret
curl -s -X DELETE "$API/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
  -H "Authorization: Bearer $TOKEN"

6. Policies

Policies control which agents (or users) can access which secrets.

# Create a policy granting an agent read access
curl -s -X POST "$API/v1/vaults/$VAULT_ID/policies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_path_pattern": "api-keys/**",
    "principal_type": "agent",
    "principal_id": "<agent-uuid>",
    "permissions": ["read"]
  }' \
  | python3 -m json.tool

# List policies for a vault
curl -s "$API/v1/vaults/$VAULT_ID/policies" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Update a policy
curl -s -X PUT "$API/v1/vaults/$VAULT_ID/policies/<policy_id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["read", "write"]
  }' \
  | python3 -m json.tool

# Delete a policy
curl -s -X DELETE "$API/v1/vaults/$VAULT_ID/policies/<policy_id>" \
  -H "Authorization: Bearer $TOKEN"

7. Agents

# Register an agent
curl -s -X POST "$API/v1/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-agent",
    "description": "A test agent",
    "intents_api_enabled": false
  }' \
  | python3 -m json.tool
# Save the returned agent_id and api_key (ocv_...)

# List agents
curl -s "$API/v1/agents" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Get a single agent
export AGENT_ID="<agent-id>"
curl -s "$API/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Update agent
curl -s -X PATCH "$API/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"renamed-agent","intents_api_enabled":true}' \
  | python3 -m json.tool

# Rotate agent API key
curl -s -X POST "$API/v1/agents/$AGENT_ID/rotate-key" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Delete (deactivate) agent
curl -s -X DELETE "$API/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Agent self-inspection

# Get the agent's own profile (includes created_by — the human who registered it)
curl -s "$API/v1/agents/me" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  | python3 -m json.tool

Agent authentication

# Exchange agent API key for JWT
curl -s -X POST "$API/v1/auth/agent-token" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent-uuid>",
    "api_key": "ocv_..."
  }' \
  | python3 -m json.tool

# Use the agent token to fetch secrets
export AGENT_TOKEN="<agent-access-token>"
curl -s "$API/v1/vaults/$VAULT_ID/secrets/api-keys/openai" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  | python3 -m json.tool

# Agent shares a secret back with its creator (the human who registered it)
curl -s -X POST "$API/v1/secrets/<secret_id>/share" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "creator",
    "expires_at": "2026-03-01T00:00:00Z",
    "max_access_count": 5
  }' \
  | python3 -m json.tool

# Create a share (by secret ID, with email invite — humans only)
curl -s -X POST "$API/v1/secrets/<secret_id>/share" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "external_email",
    "email": "colleague@example.com",
    "expires_at": "2026-03-01T00:00:00Z",
    "max_access_count": 5
  }' \
  | python3 -m json.tool

# List shares you created
curl -s "$API/v1/shares/outbound" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# List shares sent to you
curl -s "$API/v1/shares/inbound" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Accept an inbound share
curl -s -X POST "$API/v1/shares/<share_id>/accept" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Decline an inbound share
curl -s -X POST "$API/v1/shares/<share_id>/decline" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Access shared secret (public, no auth — uses share link)
curl -s "$API/v1/share/<share_id>" \
  | python3 -m json.tool

# Revoke a share
curl -s -X DELETE "$API/v1/share/<share_id>" \
  -H "Authorization: Bearer $TOKEN"

9. Chains

# List all supported chains
curl -s "$API/v1/chains" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Get a specific chain (by ID or chain_id)
curl -s "$API/v1/chains/1" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

10. Transactions (Intents API)

The agent must have intents_api_enabled: true. Use the agent's JWT. When enabled, the agent is blocked from reading private_key and ssh_key secrets directly — it must use these proxy endpoints instead.

# Submit a transaction
curl -s -X POST "$API/v1/agents/$AGENT_ID/transactions" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chain_id": 1,
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "value": "0x0",
    "data": "0x"
  }' \
  | python3 -m json.tool

# List transactions for an agent
curl -s "$API/v1/agents/$AGENT_ID/transactions" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  | python3 -m json.tool

# Get a specific transaction
curl -s "$API/v1/agents/$AGENT_ID/transactions/<tx_id>" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  | python3 -m json.tool

11. Billing & Usage

# Usage summary
curl -s "$API/v1/billing/usage" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Usage history
curl -s "$API/v1/billing/history" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

12. Audit log

# Query audit events (recent)
curl -s "$API/v1/audit/events" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# With query parameters
curl -s "$API/v1/audit/events?limit=10&action=secret.read" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

13. Organization

# List org members
curl -s "$API/v1/org/members" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Invite a member
curl -s -X POST "$API/v1/org/invite" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"newmember@example.com","role":"member"}' \
  | python3 -m json.tool

# Update member role
curl -s -X PATCH "$API/v1/org/members/<user_id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}' \
  | python3 -m json.tool

# Remove member
curl -s -X DELETE "$API/v1/org/members/<user_id>" \
  -H "Authorization: Bearer $TOKEN"

14. Security (IP rules)

# List IP rules
curl -s "$API/v1/security/ip-rules" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Create an allow rule
curl -s -X POST "$API/v1/security/ip-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cidr":"203.0.113.0/24","rule_type":"allow","description":"Office network"}' \
  | python3 -m json.tool

# Create a block rule
curl -s -X POST "$API/v1/security/ip-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cidr":"198.51.100.5/32","rule_type":"block","description":"Suspicious IP"}' \
  | python3 -m json.tool

# Delete an IP rule
curl -s -X DELETE "$API/v1/security/ip-rules/<rule_id>" \
  -H "Authorization: Bearer $TOKEN"

15. Admin endpoints

These require admin/super-admin privileges.

# List all settings
curl -s "$API/v1/admin/settings" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Update a setting
curl -s -X PUT "$API/v1/admin/settings/maintenance_mode" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"false"}' \
  | python3 -m json.tool

# Get x402 payment configuration
curl -s "$API/v1/admin/x402" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Update x402 config
curl -s -X PUT "$API/v1/admin/x402" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "facilitator_url": "https://api.cdp.coinbase.com/platform/v2/x402",
    "payment_address": "0x...",
    "network": "base-sepolia"
  }' \
  | python3 -m json.tool

# List all users
curl -s "$API/v1/admin/users" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

# Delete user (platform admin only; cascade: share links, agent created_by)
# curl -s -o /dev/null -w "%{http_code}" -X DELETE "$API/v1/admin/users/<user_id>" \
#   -H "Authorization: Bearer $TOKEN"

# Manage chains (admin)
curl -s "$API/v1/admin/chains" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

curl -s -X POST "$API/v1/admin/chains" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Polygon",
    "chain_id": 137,
    "rpc_url": "https://polygon-rpc.com",
    "explorer_url": "https://polygonscan.com",
    "is_testnet": false,
    "is_enabled": true
  }' \
  | python3 -m json.tool

# Get/update org limits
curl -s "$API/v1/admin/orgs/<org_id>/limits" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -m json.tool

16. MCP Server Testing

The MCP server runs as a stdio process. You can test it with npx:

Install and configure

npm install -g @1claw/mcp

Or add to your MCP client configuration (e.g. Claude Desktop, Cursor):

{
    "mcpServers": {
        "1claw": {
            "command": "npx",
            "args": ["-y", "@1claw/mcp"],
            "env": {
                "ONECLAW_API_URL": "https://api.1claw.xyz",
                "ONECLAW_AGENT_ID": "<agent-uuid>",
                "ONECLAW_API_KEY": "ocv_..."
            }
        }
    }
}

Test MCP tools via curl (HTTP wrapper)

If you run the MCP server with an HTTP transport (e.g. via mcp-proxy or SSE), you can test tools directly:

export MCP="http://localhost:3001"

# List vaults
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_vaults",
      "arguments": {}
    }
  }' | python3 -m json.tool

# List secrets
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_secrets",
      "arguments": {"prefix": "api-keys/"}
    }
  }' | python3 -m json.tool

# Get a secret
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_secret",
      "arguments": {"path": "api-keys/openai"}
    }
  }' | python3 -m json.tool

# Store a secret
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "put_secret",
      "arguments": {
        "path": "api-keys/new-key",
        "value": "sk-test-123",
        "type": "api_key"
      }
    }
  }' | python3 -m json.tool

# Describe a secret (metadata only)
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "describe_secret",
      "arguments": {"path": "api-keys/openai"}
    }
  }' | python3 -m json.tool

# Rotate a secret
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "rotate_and_store",
      "arguments": {
        "path": "api-keys/openai",
        "value": "sk-new-rotated-value"
      }
    }
  }' | python3 -m json.tool

# Get env bundle
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "get_env_bundle",
      "arguments": {"path": "config/prod-env"}
    }
  }' | python3 -m json.tool

# Create vault
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "create_vault",
      "arguments": {"name": "test-vault", "description": "Created via MCP"}
    }
  }' | python3 -m json.tool

# Grant access
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "grant_access",
      "arguments": {
        "vault_id": "<vault-uuid>",
        "principal_type": "agent",
        "principal_id": "<agent-uuid>",
        "permissions": ["read"]
      }
    }
  }' | python3 -m json.tool

# Share a secret
curl -s -X POST "$MCP" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "share_secret",
      "arguments": {
        "secret_id": "<secret-uuid>",
        "email": "colleague@example.com",
        "expires_at": "2026-03-01T00:00:00Z",
        "max_access_count": 5
      }
    }
  }' | python3 -m json.tool

Test MCP via stdio (interactive)

For direct stdio testing, pipe JSON-RPC messages:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  ONECLAW_API_URL=https://api.1claw.xyz \
  ONECLAW_AGENT_ID=<agent-uuid> \
  ONECLAW_API_KEY=ocv_... \
  npx @1claw/mcp

Tips

Pretty-print JSON: Pipe any response through python3 -m json.tool or jq.
Save tokens as variables: Use the token-extraction one-liner from section 2.
HTTP status codes: Add -w "\n%{http_code}\n" to any curl command to see the status code.
Verbose mode: Add -v to see full request/response headers.
x402 payment: If an endpoint returns 402, include a payment header as configured by your x402 setup.

Setup​

1. Health checks (no auth required)​

2. Authentication​

Sign up (new account)​

Email/password login​

Google OAuth login​

Refresh token​

Revoke token​

Change password​

3. Personal API Keys​

4. Vaults​

5. Secrets​

6. Policies​

7. Agents​

Agent self-inspection​

Agent authentication​

8. Sharing​

9. Chains​

10. Transactions (Intents API)​

11. Billing & Usage​

12. Audit log​

13. Organization​

14. Security (IP rules)​

15. Admin endpoints​

16. MCP Server Testing​

Install and configure​

Test MCP tools via curl (HTTP wrapper)​

Test MCP via stdio (interactive)​

Tips​