# Audit Logs

Collects audit logs tracking actions and events within the Volt.io payment platform.

**Sync Type: Incremental**

## Requirements

Before configuring this input, you need:

1. **Access to Fuzebox Dashboard**
   - Log in to your Volt.io Fuzebox account at https://fuzebox.volt.io
   - Navigate to Settings > API Credentials or Developer Settings

2. **Create OAuth2 Application**
   - Create a new OAuth2 application if you don't already have one
   - You'll receive a **Client ID** and **Client Secret**
   - Securely store these credentials

3. **API User Credentials**
   - Create or obtain API user credentials (username and password)
   - Ensure the API user has permissions to access audit log reports

4. **Required Permissions**
   - Your API user must have access to the Reporting API
   - Specifically, permissions to request and fetch audit log reports

## Details

Monad tracks the state of the input using an ascending cursor pattern with timestamps. The connector uses Volt.io's asynchronous reporting API:

1. **Request Report**: The connector requests an audit log report for a specific date range
2. **Poll Status**: The connector polls the report status every 3 seconds until it's ready (maximum 60 seconds)
3. **Fetch Data**: Once available, the connector retrieves the complete audit log data
4. **Process Records**: Events are processed and state is updated to track the last successfully ingested timestamp

### Authentication Flow

Uses OAuth2 Password Grant flow:

- Initial authentication with username/password and client credentials
- Access tokens expire after 24 hours
- The connector automatically refreshes tokens before expiry (5-minute buffer)
- Refresh tokens are stored and reused for subsequent token requests

## Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

### Settings

| Setting             | Type   | Required | Description                                                                                      |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| Base URL            | string | Yes      | Base URL of your Volt.io API instance. Use `https://api.sandbox.volt.io` for sandbox environment |
| Customer ID         | string | No       | Optional: Filter audit logs by specific customer ID                                              |
| Backfill Start Time | date | 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                                       |
| ------------- | ------ | -------- | ------------------------------------------------- |
| Client ID     | string | Yes      | OAuth2 Client ID for authentication               |
| Client Secret | string | Yes      | OAuth2 Client Secret for authentication           |
| Username      | string | Yes      | User/merchant email for authentication context    |
| Password      | string | Yes      | User/merchant password for authentication context |

## Rate Limits

The Volt.io API rate limits are **not documented** in their public API documentation. The connector implements a conservative rate limit of **10 requests per second** to avoid throttling.

### Recommendations

| Aspect             | Recommendation                                                                   |
| ------------------ | -------------------------------------------------------------------------------- |
| Conservative Limit | The connector uses 10 requests/second by default                                 |
| Initial Testing    | Start with small date ranges and monitor for rate limit errors                   |
| Monitoring         | Watch API response headers for rate limit information (if provided)              |
| Error Handling     | The connector includes retry logic, but be prepared for potential throttling     |
| Account Limits     | Contact Volt.io support to understand specific rate limits for your account tier |

**Source**: [Volt.io API Documentation](https://docs.volt.io/api-documentation/) - Rate limits not specified

### Expected Behavior

If rate limits are encountered:

- The connector will log rate limit errors
- Automatic retry with exponential backoff may occur depending on HTTP status codes
- Consider reducing sync frequency or date range size if limits are consistently hit
- Contact Volt.io support for clarification on your account's rate limits

## Troubleshooting

### Authentication Errors

**Symptoms**: `oauth token request failed with status 401` or authentication failures

**Solutions**:

- Verify your Client ID and Client Secret are correct
- Ensure your Username and Password are valid and haven't expired
- Check if credentials have been revoked or reset
- Confirm you're using the correct base URL (production vs sandbox)
- Test credentials directly in the Fuzebox dashboard

### Report Timeout Errors

**Symptoms**: `report generation timeout after 60s` or slow report generation

**Solutions**:

- The date range may be too large (though the connector chunks to 92 days)
- Volt.io API may be experiencing delays or high load
- Check Volt.io status for service issues
- Contact Volt.io support if timeouts persist
- Consider adjusting sync schedule to less busy times

### Empty or Missing Data

**Symptoms**: No audit logs returned despite activity in the platform

**Solutions**:

- Verify audit logging is enabled for your Volt.io account
- Check that the date range includes periods with actual activity
- Confirm your API user has the correct permissions to access audit logs
- Review the Volt.io Fuzebox dashboard to verify logs exist
- Ensure you're querying the correct environment (production vs sandbox)

### Connection Errors

**Symptoms**: Network timeouts or connection refused errors

**Solutions**:

- Verify network connectivity to the Volt.io API
- Check firewall rules allow HTTPS (443) to the configured base URL
- Ensure DNS resolution works for the API domain
- Test connectivity using curl or similar tools
- Verify the base URL is correct for your environment

## Related Articles

- [Volt.io API Documentation - Audit Log Reporting](https://docs.volt.io/api-documentation/#tag/Reporting/operation/post-reports-audit-log)
- [Volt.io Authentication Guide](https://docs.volt.io/global-api-payment-processing/how-api-works/api-authentication/)
- [Volt.io Reports Overview](https://docs.volt.io/reports/)
- [Fuzebox Dashboard](https://fuzebox.volt.io)

## Sample Record

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "customerName": "Acme Corp",
  "createdAt": "2025-01-08 19:23:45.000 +0000 UTC",
  "eventAction": "loggedIn",
  "context": "common",
  "domainModel": "user",
  "recordId": "8f14e45f-ceea-467a-9934-00c04f789abc",
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "userId": "a1b2c3d4-e5f6-7890-ab12-cd3456ef7890",
  "userName": "John Doe",
  "userEmail": "john.doe@example.com"
}
```

### Sample Record Fields

The audit log records contain the following key information:

- **id**: Unique identifier for the audit log entry
- **customerId**: Customer's unique identifier
- **customerName**: Customer's display name
- **createdAt**: Timestamp of when the event occurred (format: `YYYY-MM-DD HH:MM:SS.mmm +0000 UTC`)
- **eventAction**: Type of action performed (e.g., `loggedIn`, `loggedOut`, `passwordChanged`, `mfaEnabled`, `paymentCreated`, `paymentFailed`, `subscriptionChanged`, `accountUpdated`, `apiKeyCreated`, `apiKeyRevoked`, `roleAssigned`, `permissionGranted`)
- **context**: Event context category (e.g., `common`, `payment`, `user`, `security`, `access`, `configuration`)
- **domainModel**: Domain model type affected (e.g., `user`, `payment`, `customer`, `subscription`, `apiKey`, `role`, `permission`)
- **recordId**: Record's unique identifier
- **correlationId**: Correlation identifier for tracking related events
- **userId**: User's unique identifier who performed the action
- **userName**: User's display name
- **userEmail**: User's email address