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

# Audit Logs

> Track and monitor all activity in your workspace

# Audit Logs

Audit logs provide a comprehensive record of all actions taken in your Crew workspace. Use them for security monitoring, compliance requirements, and troubleshooting.

<Note>
  Full audit log access is available on Professional and Enterprise plans.
</Note>

## What's Logged

### Authentication Events

| Event                   | Description              |
| ----------------------- | ------------------------ |
| `auth.login.success`    | Successful login         |
| `auth.login.failure`    | Failed login attempt     |
| `auth.logout`           | User logged out          |
| `auth.mfa.enabled`      | MFA enabled for user     |
| `auth.mfa.disabled`     | MFA disabled for user    |
| `auth.password.changed` | Password changed         |
| `auth.password.reset`   | Password reset requested |
| `auth.session.expired`  | Session timed out        |

### User Management

| Event                      | Description          |
| -------------------------- | -------------------- |
| `user.created`             | New user added       |
| `user.updated`             | User details changed |
| `user.deleted`             | User removed         |
| `user.role.changed`        | User role modified   |
| `user.invited`             | Invitation sent      |
| `user.invitation.accepted` | User accepted invite |

### API Access

| Event             | Description                |
| ----------------- | -------------------------- |
| `api_key.created` | New API key created        |
| `api_key.revoked` | API key deleted            |
| `api_key.used`    | API key used (sampled)     |
| `api.request`     | API request made (sampled) |

### Configuration Changes

| Event              | Description                 |
| ------------------ | --------------------------- |
| `agent.created`    | Agent created               |
| `agent.updated`    | Agent configuration changed |
| `agent.deleted`    | Agent deleted               |
| `pathway.created`  | Pathway created             |
| `pathway.updated`  | Pathway modified            |
| `pathway.deleted`  | Pathway deleted             |
| `webhook.created`  | Webhook configured          |
| `webhook.updated`  | Webhook modified            |
| `webhook.deleted`  | Webhook removed             |
| `settings.updated` | Workspace settings changed  |

### Data Access

| Event                | Description                 |
| -------------------- | --------------------------- |
| `call.viewed`        | Call details accessed       |
| `transcript.viewed`  | Transcript accessed         |
| `recording.accessed` | Recording downloaded/played |
| `export.created`     | Data export requested       |
| `export.downloaded`  | Export downloaded           |

### Telephony Events

| Event              | Description          |
| ------------------ | -------------------- |
| `call.initiated`   | Outbound call placed |
| `call.answered`    | Call connected       |
| `call.ended`       | Call terminated      |
| `call.transferred` | Call transferred     |
| `sms.sent`         | SMS sent             |

## Log Format

### Structure

```json theme={null}
{
  "id": "log_abc123xyz",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "event_type": "agent.updated",
  "actor": {
    "type": "user",
    "id": "user_12345",
    "email": "admin@company.com",
    "ip_address": "203.0.113.10",
    "user_agent": "Mozilla/5.0..."
  },
  "resource": {
    "type": "agent",
    "id": "agent_sarah",
    "name": "Sarah"
  },
  "action": "update",
  "changes": {
    "persona.greeting": {
      "old": "Hello, how can I help?",
      "new": "Thank you for calling, how can I help?"
    }
  },
  "metadata": {
    "workspace_id": "ws_xyz789",
    "crew_id": "crew_abc123"
  }
}
```

### Fields

| Field        | Description                         |
| ------------ | ----------------------------------- |
| `id`         | Unique log entry ID                 |
| `timestamp`  | When the event occurred (ISO 8601)  |
| `event_type` | Type of event                       |
| `actor`      | Who performed the action            |
| `resource`   | What was affected                   |
| `action`     | The action taken                    |
| `changes`    | Before/after values (if applicable) |
| `metadata`   | Additional context                  |

## Accessing Logs

### Dashboard

View logs in the dashboard:

1. Go to **Settings** → **Audit Logs**
2. Filter by date, event type, or actor
3. Search for specific entries
4. Export for analysis

### API

Query logs programmatically:

```bash theme={null}
curl "https://api.usecrew.ai/v1/audit-logs" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Filtering

```bash theme={null}
# By event type
curl "https://api.usecrew.ai/v1/audit-logs?event_type=auth.login.failure" \
  -H "Authorization: Bearer YOUR_API_KEY"

# By date range
curl "https://api.usecrew.ai/v1/audit-logs?start=2024-01-01&end=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

# By actor
curl "https://api.usecrew.ai/v1/audit-logs?actor_email=admin@company.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

# By resource
curl "https://api.usecrew.ai/v1/audit-logs?resource_type=agent&resource_id=agent_sarah" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Pagination

```bash theme={null}
curl "https://api.usecrew.ai/v1/audit-logs?limit=100&offset=200" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Exporting Logs

### CSV Export

```bash theme={null}
curl -X POST "https://api.usecrew.ai/v1/audit-logs/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "format": "csv",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "event_types": ["auth.*", "agent.*"]
  }'
```

### JSON Export

```bash theme={null}
curl -X POST "https://api.usecrew.ai/v1/audit-logs/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "format": "json",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }'
```

### SIEM Integration

Forward logs to your SIEM:

```json theme={null}
{
  "log_forwarding": {
    "enabled": true,
    "destination": "https://your-siem.com/api/logs",
    "format": "json",
    "auth": {
      "type": "bearer",
      "token": "your_siem_token"
    },
    "events": ["auth.*", "api_key.*", "user.*"]
  }
}
```

Supported SIEM platforms:

* Splunk
* Datadog
* Sumo Logic
* Custom webhook

## Retention

### Default Retention

| Plan         | Retention Period        |
| ------------ | ----------------------- |
| Starter      | 30 days                 |
| Professional | 90 days                 |
| Enterprise   | 365 days (configurable) |

### Extended Retention

Enterprise customers can configure:

```json theme={null}
{
  "audit_log_retention": {
    "days": 730,
    "archive_to": "s3://your-bucket/audit-logs"
  }
}
```

## Alerting

### Security Alerts

Configure alerts for suspicious activity:

```json theme={null}
{
  "alerts": [
    {
      "name": "Multiple Failed Logins",
      "condition": {
        "event_type": "auth.login.failure",
        "count": 5,
        "window_minutes": 10
      },
      "action": {
        "type": "email",
        "recipients": ["security@company.com"]
      }
    },
    {
      "name": "API Key Created",
      "condition": {
        "event_type": "api_key.created"
      },
      "action": {
        "type": "webhook",
        "url": "https://your-siem.com/alerts"
      }
    }
  ]
}
```

### Alert Channels

| Channel   | Configuration       |
| --------- | ------------------- |
| Email     | Recipient addresses |
| Webhook   | Endpoint URL        |
| Slack     | Webhook URL         |
| PagerDuty | Integration key     |

## Use Cases

### Security Monitoring

Track suspicious authentication patterns:

```bash theme={null}
# Failed logins in last 24 hours
curl "https://api.usecrew.ai/v1/audit-logs?event_type=auth.login.failure&start=-24h" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Compliance Auditing

Document access to sensitive data:

```bash theme={null}
# All recording access
curl "https://api.usecrew.ai/v1/audit-logs?event_type=recording.accessed&start=2024-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Change Tracking

Review configuration changes:

```bash theme={null}
# Agent configuration changes
curl "https://api.usecrew.ai/v1/audit-logs?resource_type=agent&action=update" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### User Activity

Investigate user actions:

```bash theme={null}
# All actions by specific user
curl "https://api.usecrew.ai/v1/audit-logs?actor_email=user@company.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Log Integrity

### Immutability

Audit logs are immutable:

* Cannot be modified after creation
* Cannot be deleted (except by retention policy)
* Attempts to tamper are logged

### Verification

Enterprise customers can request:

* Cryptographic log verification
* Third-party audit attestation
* Log integrity reports

## Best Practices

<AccordionGroup>
  <Accordion title="Review logs regularly">
    Schedule weekly or monthly log reviews for security.
  </Accordion>

  <Accordion title="Set up alerts">
    Configure alerts for critical security events.
  </Accordion>

  <Accordion title="Export for long-term storage">
    Export logs before retention expiration if needed.
  </Accordion>

  <Accordion title="Integrate with SIEM">
    Forward logs to your security monitoring platform.
  </Accordion>

  <Accordion title="Document access patterns">
    Use logs to demonstrate compliance.
  </Accordion>
</AccordionGroup>

## Next Steps

* [Security Overview](/security/overview) — Security architecture
* [SSO](/enterprise/sso) — Identity management
* [Customer Responsibilities](/security/customer-responsibilities) — Your role