Audit and compliance

Every API access and relevant failure can be recorded in an audit log. Only metadata is stored: path, action, actor, timestamp, IP. Secret values are never logged.

• GET /v1/audit/events with filters: resource_id, actor_id, action, from, to, limit, offset
• Each event carries prev_event_id and integrity_hash forming a SHA-256 hash chain
• Modifying or deleting any event breaks the chain for every later entry
• The app runs as vault_app, which cannot INSERT into audit_events directly

1. 1

   Set your API key. Replace with your 1ck_ key from Settings → API Keys.

   bash Copy

   export TOKEN=1ck_your_key_here

2. 2

   Query recent secret reads.

   bash Copy

   curl "https://api.1claw.co/v1/audit/events?action=secret.read&limit=25" \
     -H "Authorization: Bearer $TOKEN"

3. 3

   Notice the response includes metadata only, plus prev_event_id and integrity_hash for chain verification. The actor_id shown is an example UUID.

   json Copy

   {
     "events": [{
       "action": "secret.read",
       "actor_id": "7e3ce911-e2a7-4f3a-8609-1851515d140f",
       "prev_event_id": "evt_a1b2c3d4",
       "integrity_hash": "sha256:9f86d08...",
       "details": { "path": "keys/eth-signer" },
       "created_at": "2026-02-27T14:00:00Z"
     }],
     "count": 1
   }

4. 4

   Export an agent UUID from a prior lesson or from the dashboard. If the list is empty, read a secret first (see Foundations), then re-query.

   bash Copy

   export AGENT_ID="your-agent-uuid"

5. 5

   Filter by a single actor to review one agent's activity.

   bash Copy

   curl "https://api.1claw.co/v1/audit/events?actor_id=$AGENT_ID&limit=50" \
     -H "Authorization: Bearer $TOKEN"

6. 6

   To forward events to your SIEM, register an AuditSink when constructing the TypeScript SDK client. See the @1claw/sdk package documentation for the AuditSink plugin interface.

   typescript Copy

   import { OneClaw, AuditSink } from "@1claw/sdk";
   
   const sink: AuditSink = {
     send(event) {
       fetch("https://your-siem.example.com/ingest", {
         method: "POST",
         body: JSON.stringify(event),
       });
     },
   };
   
   const client = new OneClaw({
     token: process.env.ONECLAW_TOKEN,
     auditSink: sink,
   });

You can now query the audit log by action and actor and explain why the chain plus SECURITY DEFINER insert makes it tamper-evident, which supports SOC 2 controls like CC6 and CC7.

Where this goes wrong in practice. Audit logs are written continuously and read rarely, so their defects surface at the least convenient moment.

• Retention is shorter than the question. Regulators ask about periods measured in years and default retention is measured in months, which is discovered during the first audit rather than before it.
• Nobody has tested completeness. Negative assurance depends on an event necessarily being recorded, and that claim needs evidence rather than confidence.
• The log is queried only after incidents. A log nobody reads routinely is a log whose gaps nobody knows about, and the gaps are what an incident will find.
• Attribution collapses onto one identity. Every action attributed to "the agent" satisfies retention and answers nothing, which is why identity separation is an audit concern rather than a tidiness one.