# Enterprise Audit Logs

## Overview

The Slack Enterprise Audit Logs input continuously monitors and retrieves comprehensive audit logs from your Slack Enterprise Grid organization. It captures critical security events including user authentication activities, channel operations, app installations, file management, workspace changes, and administrative actions. This integration enables real-time security monitoring, compliance reporting, and forensic analysis of your Slack Enterprise infrastructure.

**Sync Type: Incremental**

## Prerequisites

- Active Slack Enterprise Grid subscription
- Organization Owner or Org Admin role required for audit log access
- **Admin Authorization Required**: Organization administrators must approve the installation of apps that request audit log access permissions

## OAuth Token Setup

To access Slack Enterprise Audit Logs, you need to create a Slack app with the appropriate OAuth scopes.

### 1. Create a Slack App
1. **Navigate to Slack API**
   - Go to [https://api.slack.com/apps](https://api.slack.com/apps)
   - Sign in with your Slack account

2. **Create New App**
   - Click **Create New App**
   - Choose **From scratch**
   - Provide an app name (e.g., "Audit Logs Integration")
   - Select your Enterprise Grid organization
   - When completed, you will be redirected to the "Basic Information" page for your app

### 2. Grant Permissions
1. **Navigate to OAuth & Permissions**
   - In the left sidebar, click **OAuth & Permissions**

2. **Add Bot Token Scopes**
   - Under **Scopes** > **Bot Token Scopes**, add the following scope:
     - `team:read` - View the name, email domain, and icon for workspaces the app is connected to

3. **Add User Token Scopes**
   - Under **Scopes** > **User Token Scopes**, add the following scope:
     - `auditlogs:read` - View events from all workspaces, channels and users (Enterprise Grid only)

### 3. Enable Organization Level Apps
- If not already enabled, go to **Org Level Apps** and opt in to enable apps for the whole organization
- This step is required for Enterprise Grid audit log access

### 4. Install App
1. **Install to Workspace**
   - Scroll to the top of the **OAuth & Permissions** page
   - Click the **Install to workspace** button
   - Click **Allow** when prompted
   - **Important**: Apps requesting audit log access require administrator approval

2. **Wait for Admin Approval (if needed)**
   - If you are not an organization admin, the app installation may be pending approval
   - Organization administrators will receive a notification to approve the app
   - The installation must be approved before you can proceed

3. **Copy User OAuth Token**
   - After installation and approval, copy the **User OAuth Token**
   - This token starts with `xoxp-` and will be used in the configuration
   - Store it securely - treat it as a sensitive credential

**Note**: If making scope changes to an app, be sure to reinstall the app to the workspace for the changes to take effect.

## Configuration

### Settings

| Setting             | Type    | Required | Description                                                                                                                                                                                      |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Use synthetic data  | boolean | No       | Generate synthetic demo data instead of connecting to the real data source.                                                                                                                      |
| Backfill start time | string | No | The date to start fetching data from. If not specified, no past records will be fetched. |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |

### Secrets

| Secret           | Type   | Required | Description                                                                                          |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| User OAuth Token | string | Yes      | User OAuth Token with `auditlogs:read` scope from your Slack app configuration (starts with `xoxp-`) |

## Details

Monad uses the `date_create` timestamp field from audit log entries to implement incremental synchronization. The connector tracks the timestamp of the last successfully processed event and only fetches newer events on subsequent runs. If this is the first time running the connector, a full sync of available audit events is performed.

### Important Limitations
- **Data Retention**: Slack Enterprise Grid retains audit logs for different periods based on your plan
- **Historical Data**: Audit logs are only available from March 2018 onwards
- **Enterprise Grid Only**: This feature is only available for Enterprise Grid organizations

## Connector Limitations

- **Enterprise Grid Required**: This connector only works with Slack Enterprise Grid organizations
- **Rate Limits**: Subject to Slack's API rate limits which may affect data collection speed for high-volume organizations
- **Historical Limit**: Cannot fetch data older than March 2018
- **Token Scope**: OAuth token must have the `auditlogs:read` scope
- **Organization Access**: App must be installed at the organization level

## Related Articles

- [Slack Audit Logs API Documentation](https://api.slack.com/admins/audit-logs)
- [Slack Enterprise Grid Overview](https://slack.com/enterprise)
- [Creating Slack Apps](https://api.slack.com/start/overview)
- [OAuth Scopes for Slack Apps](https://api.slack.com/scopes)

## Sample Record

```json
{
  "id": "12345678-1234-1234-1234-123456789012",
  "date_create": 1635724800,
  "action": "user_login",
  "actor": {
    "type": "user",
    "user": {
      "id": "W1234567890",
      "name": "john.doe",
      "email": "john.doe@company.com"
    }
  },
  "entity": {
    "type": "user",
    "user": {
      "id": "U0987654321",
      "name": "jane.smith",
      "email": "jane.smith@company.com"
    }
  },
  "context": {
    "location": {
      "type": "enterprise",
      "id": "E1234567890",
      "name": "Acme Corp",
      "domain": "acme-corp"
    },
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "ip_address": "203.0.113.1"
  }
}
```