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

# Audit Logs

> Query EngageFabric audit logs for compliance and debugging. Track admin actions, API key usage, security events, and configuration changes.

## Overview

EngageFabric's Audit Logging system provides comprehensive tracking of all administrative actions, security events, and resource changes. This is essential for:

* **Compliance**: Meet regulatory requirements (SOC 2, GDPR)
* **Security Monitoring**: Detect suspicious activity in real-time
* **Accountability**: Track who made changes and when
* **Debugging**: Investigate issues with full audit trails

<Note>
  Audit logs are only accessible to users with **Admin** or **Owner** roles.
</Note>

***

## Querying Audit Logs

### List Audit Logs

Retrieve paginated audit logs with optional filters:

```bash theme={null}
curl -X GET "https://api.engagefabric.com/admin/audit-logs" \
  -H "Authorization: Bearer your-jwt-token" \
  -G \
  -d "tenantId=your-tenant-id" \
  -d "limit=50" \
  -d "offset=0"
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "log-uuid",
      "tenantId": "tenant-uuid",
      "projectId": "project-uuid",
      "adminId": "admin-uuid",
      "eventType": "XP_GRANTED",
      "action": "adjust_xp",
      "resource": "player",
      "resourceId": "player-uuid",
      "changes": {
        "before": { "xp": 1000 },
        "after": { "xp": 1500 }
      },
      "details": {
        "playerId": "player-uuid",
        "playerName": "John Doe",
        "amount": 500,
        "reason": "Customer support compensation"
      },
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2025-12-01T10:30:00Z"
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0
}
```

### Get Single Audit Log

```bash theme={null}
curl -X GET "https://api.engagefabric.com/admin/audit-logs/{logId}" \
  -H "Authorization: Bearer your-jwt-token"
```

***

## Security Monitoring

### Suspicious Activity

Retrieve audit logs flagged as suspicious:

```bash theme={null}
curl -X GET "https://api.engagefabric.com/admin/audit-logs/suspicious/activity" \
  -H "Authorization: Bearer your-jwt-token" \
  -G \
  -d "tenantId=your-tenant-id" \
  -d "limit=20"
```

Suspicious activity includes:

* Multiple failed authentication attempts
* Unusual API key usage patterns
* High-volume data exports
* Permission escalation attempts

### Recent Security Events

Get security-related events from the past hours:

```bash theme={null}
curl -X GET "https://api.engagefabric.com/admin/audit-logs/security/events" \
  -H "Authorization: Bearer your-jwt-token" \
  -G \
  -d "hours=24" \
  -d "limit=100"
```

***

## Resource Audit Trail

Track all changes to a specific resource:

```bash theme={null}
curl -X GET "https://api.engagefabric.com/admin/audit-logs/resource/player/{playerId}" \
  -H "Authorization: Bearer your-jwt-token" \
  -G \
  -d "limit=50"
```

**Supported Resource Types:**

* `player` - Player records
* `quest` - Quest definitions
* `adventure` - Adventure/season configurations
* `leaderboard` - Leaderboard settings
* `rule` - Rules engine rules
* `api-key` - API key management

***

## Event Types

| Event Type         | Description                         |
| ------------------ | ----------------------------------- |
| `XP_GRANTED`       | XP added or removed from player     |
| `CURRENCY_GRANTED` | Currency adjusted                   |
| `LEVEL_UP`         | Player level increased              |
| `QUEST_COMPLETED`  | Quest marked as completed           |
| `BADGE_AWARDED`    | Badge granted to player             |
| `API_KEY_CREATED`  | New API key generated               |
| `API_KEY_REVOKED`  | API key deactivated                 |
| `USER_LOGIN`       | Admin user logged in                |
| `USER_LOGOUT`      | Admin user logged out               |
| `SETTINGS_CHANGED` | Project or tenant settings modified |
| `RULE_CREATED`     | New rule added to rules engine      |
| `RULE_UPDATED`     | Existing rule modified              |

***

## Audit Log Retention

| Tier           | Retention Period         |
| -------------- | ------------------------ |
| **Free**       | 7 days                   |
| **Starter**    | 30 days                  |
| **Pro**        | 90 days                  |
| **Enterprise** | Custom (up to unlimited) |

<Warning>
  Audit logs older than your retention period are automatically deleted. Export important logs before they expire.
</Warning>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Regular Reviews" icon="magnifying-glass">
    Schedule weekly reviews of audit logs to identify unusual patterns or unauthorized access attempts.
  </Card>

  <Card title="Export for Compliance" icon="download">
    Export audit logs regularly for long-term storage and compliance requirements.
  </Card>

  <Card title="Set Up Alerts" icon="bell">
    Configure webhook notifications for critical security events to enable real-time monitoring.
  </Card>

  <Card title="Document Actions" icon="file-lines">
    Always provide meaningful reasons when making admin adjustments to maintain a clear audit trail.
  </Card>
</CardGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Player Management" icon="user" href="/guides/player-management">
    Learn about admin player operations that generate audit logs
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Set up notifications for audit events
  </Card>
</CardGroup>