> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhara.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Company name is Akhara AI (never Rubric AI). Keep lowercase rubric/rubrics only when meaning grading criteria.
> Expert Review (docs path talent/) is enterprise BYO experts for audit and review: invite customer specialists; do not pitch Akhara recruiting or a public expert career portal. RLHF and domain writing are secondary work types.
> Prefer concrete API examples against public hosts: Environments eval API https://agi.akhara.ai, Control plane PDP https://api.akhara.dev, Evaluation https://app.akhara.ai / https://api.akhara.ai, Expert Review portal https://talent.akhara.ai.
> Do not invent a public hostname for private orchestrators or env API internals.
> Do not confuse control-plane latches with Environments confirmation latches.
> Environments SDK/API examples: curl against https://agi.akhara.ai. Evaluation SDK: from akhara import Akhara and AKHARA_API_KEY.
> Start with /llms.txt for the docs index and OpenAPI links; fetch individual pages as .md exports.

# Audit Logs

> Complete audit trail for compliance, security, and operational visibility into your Akhara environment.

## Overview

Akhara maintains comprehensive audit logs of all actions taken within your organization. Every API call, user action, and system event is recorded with full context for compliance, security investigations, and operational debugging.

<Callout type="info" title="HIPAA Compliance">
  Audit logs are a core component of HIPAA compliance. Akhara retains logs for 7 years by default and provides tamper-evident storage with cryptographic verification.
</Callout>

## What's Logged

### User Actions

| Event Type          | Description              | Example                                                     |
| ------------------- | ------------------------ | ----------------------------------------------------------- |
| `user.login`        | User authentication      | SSO login via Okta                                          |
| `user.logout`       | User session ended       | Manual logout                                               |
| `user.invite`       | New user invited         | Invited [dr.jones@example.com](mailto:dr.jones@example.com) |
| `user.role_changed` | Role assignment modified | Changed from Viewer to Reviewer                             |
| `user.removed`      | User removed from org    | Removed user\_abc123                                        |

### Data Access

| Event Type            | Description                | Example                      |
| --------------------- | -------------------------- | ---------------------------- |
| `dataset.created`     | New dataset created        | Created "Q1 Triage Calls"    |
| `dataset.accessed`    | Dataset viewed or queried  | Listed samples in ds\_xyz    |
| `sample.viewed`       | Individual sample accessed | Viewed sample smp\_123       |
| `sample.phi_accessed` | PHI fields accessed        | Accessed transcript with PHI |
| `dataset.exported`    | Data exported              | Exported 500 samples to CSV  |
| `dataset.deleted`     | Dataset deleted            | Deleted ds\_old\_test        |

### Evaluation Events

| Event Type             | Description          | Example                             |
| ---------------------- | -------------------- | ----------------------------------- |
| `evaluation.created`   | Evaluation started   | Created eval\_abc with 3 evaluators |
| `evaluation.completed` | Evaluation finished  | Completed with 94% avg score        |
| `evaluation.failed`    | Evaluation errored   | Failed: invalid evaluator config    |
| `evaluation.cancelled` | Evaluation cancelled | Cancelled by user\_xyz              |

### Review Events

| Event Type          | Description               | Example                         |
| ------------------- | ------------------------- | ------------------------------- |
| `review.assigned`   | Task assigned to reviewer | Assigned 10 samples to dr.smith |
| `review.submitted`  | Review completed          | Submitted grade: under-triaged  |
| `review.overridden` | AI score overridden       | Changed triage from 85 to 62    |
| `review.escalated`  | Case escalated            | Escalated to senior reviewer    |

### Administrative Events

| Event Type                 | Description             | Example                     |
| -------------------------- | ----------------------- | --------------------------- |
| `project.created`          | New project created     | Created "Voice Triage v3"   |
| `project.settings_changed` | Project config modified | Updated evaluator weights   |
| `api_key.created`          | New API key generated   | Created key for CI pipeline |
| `api_key.revoked`          | API key revoked         | Revoked compromised key     |
| `webhook.configured`       | Webhook added/modified  | Added Slack notification    |

## Log Structure

Each audit log entry contains:

```json theme={null}
{
  "id": "log_8f3k2m9x",
  "timestamp": "2024-01-15T14:32:18.042Z",
  "event_type": "sample.phi_accessed",
  "actor": {
    "type": "user",
    "id": "user_abc123",
    "email": "dr.smith@hospital.org",
    "ip_address": "192.168.1.42",
    "user_agent": "Mozilla/5.0..."
  },
  "resource": {
    "type": "sample",
    "id": "smp_xyz789",
    "project": "proj_triage_v2",
    "dataset": "ds_q1_calls"
  },
  "context": {
    "fields_accessed": ["transcript", "patient_age"],
    "access_justification": "Clinical review assignment",
    "session_id": "sess_m8k2p"
  },
  "org_id": "org_healthcare_inc",
  "environment": "production"
}
```

## Querying Audit Logs

### Via SDK

```python theme={null}
from akhara import Akhara
from datetime import datetime, timedelta

client = Akhara()

# Get recent PHI access events
phi_logs = client.audit.list(
    event_types=["sample.phi_accessed", "dataset.exported"],
    start_time=datetime.now() - timedelta(days=7),
    limit=100
)

for log in phi_logs:
    print(f"{log.timestamp}: {log.actor.email} - {log.event_type}")

# Get all actions by a specific user
user_activity = client.audit.list(
    actor_id="user_abc123",
    start_time=datetime.now() - timedelta(days=30)
)

# Get events for a specific resource
sample_history = client.audit.list(
    resource_type="sample",
    resource_id="smp_xyz789"
)
```

### Via API

```bash theme={null}
curl "https://api.akhara.ai/v1/audit/logs?event_type=sample.phi_accessed&limit=50" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"
```

### Via Dashboard

Navigate to **Organization Settings** → **Audit Logs** to access the visual log explorer with:

* Full-text search across all log fields
* Filtering by event type, user, resource, and time range
* Export to CSV/JSON for compliance reporting
* Real-time streaming for active monitoring

## Retention & Storage

| Plan       | Retention Period       | Storage        | Export          |
| ---------- | ---------------------- | -------------- | --------------- |
| Starter    | 90 days                | Standard       | CSV             |
| Pro        | 1 year                 | Standard       | CSV, JSON       |
| Enterprise | 7 years (configurable) | Tamper-evident | CSV, JSON, SIEM |

### Tamper-Evident Storage

Enterprise audit logs use append-only storage with cryptographic chaining:

```python theme={null}
# Verify log integrity
verification = client.audit.verify_integrity(
    start_time="2024-01-01T00:00:00Z",
    end_time="2024-01-31T23:59:59Z"
)

print(f"Logs verified: {verification.valid}")
print(f"Chain hash: {verification.chain_hash}")
print(f"Entries checked: {verification.entry_count}")
```

## SIEM Integration

Export audit logs to your Security Information and Event Management system:

<CardGroup cols={2}>
  <Card title="Splunk" icon="chart-mixed">
    Native integration via HTTP Event Collector
  </Card>

  <Card title="Datadog" icon="dog">
    Log forwarding with custom parsing rules
  </Card>

  <Card title="Sumo Logic" icon="cloud">
    Hosted collector integration
  </Card>

  <Card title="Custom Webhook" icon="webhook">
    Real-time forwarding to any endpoint
  </Card>
</CardGroup>

### Configure SIEM Export

```python theme={null}
# Set up Splunk integration
client.audit.configure_export(
    destination="splunk",
    config={
        "hec_endpoint": "https://splunk.example.com:8088",
        "hec_token": "your-hec-token",
        "index": "rubric_audit",
        "source_type": "akhara:audit"
    },
    event_types=["*"],  # All events, or specify a list
    real_time=True
)
```

## Compliance Reports

Generate pre-formatted reports for compliance audits:

```python theme={null}
# Generate HIPAA access report
report = client.audit.generate_report(
    report_type="hipaa_access",
    start_time="2024-01-01",
    end_time="2024-03-31",
    format="pdf"
)

# Download report
report.download("hipaa_q1_2024.pdf")
```

### Available Report Types

| Report            | Description                                        | Frequency |
| ----------------- | -------------------------------------------------- | --------- |
| `hipaa_access`    | All PHI access with user, time, justification      | Quarterly |
| `user_activity`   | Complete user action summary                       | Monthly   |
| `security_events` | Failed logins, key revocations, permission changes | Weekly    |
| `data_lifecycle`  | Dataset creation, modification, deletion           | Monthly   |

## Alerting

Configure real-time alerts for security-sensitive events:

```python theme={null}
# Alert on suspicious activity
client.audit.create_alert(
    name="unusual_phi_access",
    description="Alert when PHI accessed outside business hours",
    condition={
        "event_type": "sample.phi_accessed",
        "time_outside": {"start": "09:00", "end": "18:00", "timezone": "America/New_York"}
    },
    channels=["email", "slack"],
    recipients=["security@example.com"]
)

# Alert on bulk exports
client.audit.create_alert(
    name="bulk_export_alert",
    description="Alert on large data exports",
    condition={
        "event_type": "dataset.exported",
        "threshold": {"field": "context.record_count", "operator": "gt", "value": 1000}
    },
    channels=["pagerduty"]
)
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Regular Review" icon="calendar-check">
    Review audit logs weekly for anomalies and unauthorized access attempts
  </Card>

  <Card title="SIEM Integration" icon="shield">
    Forward logs to your SIEM for centralized security monitoring
  </Card>

  <Card title="Retention Policy" icon="clock">
    Configure retention to meet regulatory requirements (7 years for HIPAA)
  </Card>

  <Card title="Alert Configuration" icon="bell">
    Set up alerts for PHI access, failed logins, and permission changes
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="Role-Based Access Control" icon="lock" href="/evaluation/api-reference/authentication/rbac">
    Configure who can access what
  </Card>

  <Card title="Audit & Provenance APIs" icon="code" href="/evaluation/api-reference/authentication/audit-logs">
    Programmatic access to audit logs
  </Card>
</CardGroup>