Skip to main content

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:

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.

Configuration​

Settings​

SettingTypeRequiredDefaultDescription
Backfill Start TimestringNo-The date to start fetching data from. If not specified, no past records will be fetched.

Secrets​

SecretTypeRequiredDescription
api_keystringYesAPI 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: 
    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