Skip to main content

​
Audit

Docyard maintains immutable audit logs for every action that happens in the lake. This ensures compliance, security, and accountability.

​
What’s Logged

​
Artifact Uploads

Every artifact upload is logged: 
{
  "event": "artifact_uploaded",
  "timestamp": "2026-03-15T10:30:00Z",
  "actor": {
    "type": "distributor",
    "id": "dist-abc123",
    "name": "Acme Insurance"
  },
  "resource": {
    "type": "artifact",
    "id": "art-xyz789"
  },
  "details": {
    "ramp_id": "ramp-def456",
    "template": "Insurance Declaration",
    "locks": {
      "policy_number": "POL-12345678",
      "effective_date": "2026-03-15"
    },
    "threshold": 20
  }
}

​
Retrieval Attempts

Every retrieval attempt is logged: 
{
  "event": "artifact_retrieval_attempted",
  "timestamp": "2026-03-15T14:30:00Z",
  "actor": {
    "type": "collector",
    "id": "coll-xyz789",
    "name": "FirstCity Bank"
  },
  "resource": {
    "type": "artifact",
    "id": "art-xyz789"
  },
  "details": {
    "dock_id": "dock-abc123",
    "keys_provided": ["policy_number"],
    "score": 20,
    "threshold": 20,
    "result": "granted"
  }
}

​
Access Denials

Failed retrieval attempts are also logged: 
{
  "event": "artifact_retrieval_denied",
  "timestamp": "2026-03-15T14:35:00Z",
  "actor": {
    "type": "collector",
    "id": "coll-unknown",
    "name": "Unknown Entity"
  },
  "resource": {
    "type": "artifact",
    "id": "art-xyz789"
  },
  "details": {
    "dock_id": "dock-unknown",
    "keys_provided": [],
    "score": 0,
    "threshold": 20,
    "result": "denied",
    "reason": "insufficient_keys"
  }
}

​
Template Changes

Template creation and updates: 
{
  "event": "template_created",
  "timestamp": "2026-03-10T09:00:00Z",
  "actor": {
    "type": "distributor",
    "id": "dist-abc123",
    "name": "Acme Insurance"
  },
  "resource": {
    "type": "template",
    "id": "tmpl-abc123"
  },
  "details": {
    "template_name": "Acme Declaration Page",
    "locks_count": 4,
    "status": "draft"
  }
}

​
Admin Actions

Admin vetting and approvals: 
{
  "event": "template_approved",
  "timestamp": "2026-03-10T11:00:00Z",
  "actor": {
    "type": "admin",
    "id": "admin-001",
    "name": "Docyard Admin"
  },
  "resource": {
    "type": "template",
    "id": "tmpl-abc123"
  },
  "details": {
    "previous_status": "pending_approval",
    "new_status": "published"
  }
}

​
Log Structure

Each audit log entry contains:
FieldDescriptionExample
eventType of eventartifact_uploaded
timestampWhen it happened2026-03-15T10:30:00Z
actorWho did it{ type, id, name }
resourceWhat was affected{ type, id }
detailsEvent-specific data{ ... }
metadataAdditional context{ ip, user_agent }

​
Querying Logs

​
List All Logs

GET /api/v1/audit/logs

{
  "logs": [
    { "event": "artifact_uploaded", "timestamp": "2026-03-15T10:30:00Z" },
    { "event": "artifact_retrieved", "timestamp": "2026-03-15T14:30:00Z" }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1250 }
}

​
Filter by Event Type

GET /api/v1/audit/logs?event=artifact_retrieval_attempted

​
Filter by Actor

GET /api/v1/audit/logs?actor_type=collector&actor_id=coll-xyz789

​
Filter by Time Range

GET /api/v1/audit/logs?after=2026-03-01T00:00:00Z&before=2026-03-31T23:59:59Z

​
Filter by Resource

GET /api/v1/audit/logs?resource_type=artifact&resource_id=art-xyz789

​
Get Entity History

Get all events for a specific artifact: 
GET /api/v1/audit/entity/art-xyz789

{
  "entity_id": "art-xyz789",
  "entity_type": "artifact",
  "events": [
    {
      "event": "artifact_uploaded",
      "timestamp": "2026-03-15T10:30:00Z",
      "actor": "Acme Insurance"
    },
    {
      "event": "artifact_retrieved",
      "timestamp": "2026-03-15T14:30:00Z",
      "actor": "FirstCity Bank"
    },
    {
      "event": "artifact_retrieved",
      "timestamp": "2026-03-15T15:00:00Z",
      "actor": "FirstCity Bank"
    }
  ]
}

​
Retention Policies

Audit logs are retained based on document type:
Document TypeRetention Period
Insurance declarations7 years
Loan agreements10 years
Birth certificatesPermanent
General documents3 years

​
Compliance Use Cases

​
For Distributors

  • Prove artifact was uploaded on a specific date
  • Track who retrieved your documents
  • Monitor for unauthorized access attempts

​
For Collectors

  • Demonstrate chain of custody for audits
  • Prove documents were retrieved legally
  • Track internal document access

​
For Docyard

  • Detect anomalous access patterns
  • Investigate security incidents
  • Generate compliance reports

​
Exporting Logs

​
Export to JSON

GET /api/v1/audit/export?format=json&after=2026-01-01

​
Export to CSV

GET /api/v1/audit/export?format=csv&after=2026-01-01

​
Export for Specific Entity

GET /api/v1/audit/entity/art-xyz789/export?format=pdf

​
Immutability

Audit logs cannot be modified or deleted:
  • Append-only storage
  • Cryptographic signatures
  • Distributed across multiple nodes
  • Tamper-evident timestamps
Any attempt to modify logs creates a new log entry recording the modification attempt itself.

​
Next Steps