Policies and scoped access

A fresh agent has zero access. Its JWT carries an empty scope list until a human writes a policy. Policies tie a principal to path patterns and permissions, so you decide exactly what an agent can touch.

• * matches one path segment
• ** matches zero or more segments (any depth)
• read: GET a value and list metadata
• write: PUT and DELETE at matching paths

1. 1

   Export your keys and IDs. Use the values saved from Lesson 1.

   bash Copy

   export ONECLAW_API_KEY="1ck_your_key_here"
   export VAULT_ID="your-vault-uuid-here"
   export AGENT_ID="your-agent-uuid-here"

2. 2

   Create a policy that lets the agent read only api-keys/openai. The pattern is a single path, so the agent cannot reach anything else in the vault.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/vaults/$VAULT_ID/policies \
     -H "Authorization: Bearer $ONECLAW_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"principal_type":"agent","principal_id":"'$AGENT_ID'","permissions":["read"],"secret_path_pattern":"api-keys/openai"}'

3. 3

   Re-exchange the agent key for a fresh JWT. The old token was revoked by the policy change.

   bash Copy

   TOKEN=$(curl -s -X POST https://api.1claw.co/v1/auth/agent-token \
     -H "Content-Type: application/json" \
     -d '{"agent_id":"'$ONECLAW_AGENT_ID'","api_key":"'$ONECLAW_AGENT_KEY'"}' | jq -r .access_token)

4. 4

   Read the allowed path (works), then try a different path. Both 403 (forbidden) and 404 (not found) confirm the agent cannot access that path.

   bash Copy

   curl -s https://api.1claw.co/v1/vaults/$VAULT_ID/secrets/api-keys/openai \
     -H "Authorization: Bearer $TOKEN"
   curl -s https://api.1claw.co/v1/vaults/$VAULT_ID/secrets/api-keys/stripe \
     -H "Authorization: Bearer $TOKEN"

Your agent can now read one secret path and nothing else, and any policy change takes effect on the very next request.

Policy Engine v2 (v0.47) added three fields that turn policies from a flat allow-list into a real evaluation model: effect, priority, and attribute_conditions.

• effect: "allow" or "deny". A deny rule lets you punch a hole in a broad allow.
• priority: an integer; higher wins when two policies both match the same path.
• attribute_conditions: JSONB for fine-grained matching beyond path, IP, and time.

1. 1

   Grant the agent broad read access across the vault.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/vaults/$VAULT_ID/policies \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "principal_type": "agent", "principal_id": "'$AGENT_ID'",
       "path_pattern": "app/**", "permissions": ["read"],
       "effect": "allow", "priority": 10
     }'

2. 2

   Now carve out the one prefix it must never read, with a higher priority so it wins the overlap.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/vaults/$VAULT_ID/policies \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "principal_type": "agent", "principal_id": "'$AGENT_ID'",
       "path_pattern": "app/billing/**", "permissions": ["read"],
       "effect": "deny", "priority": 100
     }'

3. 3

   Verify. The first read succeeds, the second is denied by the higher-priority deny rule.

   bash Copy

   1claw secret get app/search/api-key   # allowed
   1claw secret get app/billing/stripe   # denied