# Events

Ingests comprehensive audit events from Opal Security tracking user actions, access requests, group management, resource modifications, integrations, reviews, policies, and administrative activities for security monitoring and compliance.

**Sync Type: Incremental**

## Overview

The Opal Events connector retrieves audit log data from Opal Security's centralized identity and access management platform. Opal Security provides visibility into access governance across cloud applications, infrastructure, and SaaS tools.

## Requirements

Before configuring this input, you need to generate an API key from Opal Security:

### Option 1: Service User API Key (Recommended)

Service users are dedicated identities for API access with scoped permissions.

1. Navigate to **Organization Settings → Service Users**
2. Create a new service user or select an existing one
3. Assign appropriate Opal roles to scope permissions (typically read access to events)
4. Add the service user to necessary groups
5. Go to the **API Keys** tab
6. Click **Generate API Key**
7. Optionally set an expiration date for security
8. Copy and securely store the API key

**Note**: A maximum of 2 API keys can be created per service user.

### Option 2: Personal Access Token

Admins can create personal access tokens from user settings.

1. Go to **User → Settings**
2. Navigate to **API Tokens** section
3. Click **Generate Token**
4. Select permission level:
   - **Read-only**: For audit log access only (recommended)
   - **Full-access**: For complete API access
5. Optionally set an expiration date
6. Copy and securely store the token

**Required Permissions**: The API key or token must have read access to audit events. For service users, ensure the assigned role includes event read permissions.

For more details, see [Opal Authentication Documentation](https://docs.opal.dev/reference/authentication).

## Configuration

### Settings

| Setting             | Type   | Required | Default     | Description                                                                                                                        |
| ------------------- | ------ | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 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                                                                                                                |
| ------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| api_key | string | Yes      | API Key (Bearer token) generated from Opal Security. This can be either a service user API key or a personal access token. |

## State Management

The connector implements cursor-based incremental data fetching:

1. **Initial Sync**: On first run, fetches events starting from `backfill_start_time` (or 90 days ago if not specified)
2. **Incremental Updates**: Subsequent runs fetches only new events since the last successful sync
3. **Checkpointing**: State is saved after each page to ensure recovery from interruptions
4. **Deduplication**: Events are tracked by their unique `id` and `created_at` timestamp to prevent duplicates

The connector automatically handles pagination cursors provided by Opal's API, ensuring complete event coverage without gaps.

## Troubleshooting

### 1. Authentication Errors

**Error**: "API Key is required" or 401 Unauthorized

**Solutions**:

- Verify the API key is correctly copied (no extra spaces)
- Check if the API key has expired (service user keys can have expiration dates)
- Ensure the service user or user has read permissions for events
- Confirm the API key hasn't been revoked in Opal Security settings
- Test the key manually with curl:
  ```bash
  curl -H "Authorization: Bearer YOUR_API_KEY" \
       https://api.opal.dev/v1/events?page_size=1
  ```

### 2. No Events Returned

**Error**: Successful connection but no events in output

**Solutions**:

- Check if `backfill_start_time` is within the retention window
- Verify there are actual events in Opal during the specified time range
- Review Opal's event logs directly in the web console to confirm data exists
- Ensure the API key has sufficient permissions (not restricted to specific resources)
- Try without `backfill_start_time` to fetch default range

## Related Resources

- [Opal Security Official Documentation](https://docs.opal.dev/)
- [Opal API Authentication](https://docs.opal.dev/reference/authentication)
- [Opal Event Types](https://docs.opal.dev/docs/event-types)
- [Opal Events Streaming](https://docs.opal.dev/v3.2/docs/events-streaming)