# Audit Logs

Collects audit logs from the Genesys Cloud platform for monitoring administrative actions and configuration changes.

**Sync Type: Incremental**

## Requirements

Before connecting Monad to Genesys Cloud, you need:

1. **Genesys Cloud Region**
   - Your organization is hosted in a specific region
   - Identify from your Genesys Cloud login URL (see table below)
   - Example: If you login to `app.mypurecloud.com`, your region is `us-east-1`

2. **OAuth2 Client Credentials**
   - Requires a Client Credentials grant type OAuth application
   - Client ID and Client Secret
   - Must have the `audits:audit:view` permission

### Region Mapping

Find your region by checking your Genesys Cloud login URL:

| Login URL | Region |
| --------- | ------ |
| app.mypurecloud.com | us-east-1 |
| app.usw2.pure.cloud | us-west-2 |
| app.cac1.pure.cloud | ca-central-1 |
| app.mypurecloud.ie | eu-west-1 |
| app.euw2.pure.cloud | eu-west-2 |
| app.mypurecloud.de | eu-central-1 |
| app.mypurecloud.com.au | ap-southeast-2 |
| app.mypurecloud.jp | ap-northeast-1 |
| app.aps1.pure.cloud | ap-south-1 |
| app.apne2.pure.cloud | ap-northeast-2 |
| app.sae1.pure.cloud | sa-east-1 |
| app.mec1.pure.cloud | me-central-1 |

### Creating OAuth2 Client Credentials

1. Log in to your Genesys Cloud organization as an administrator
2. Navigate to **Admin** > **Integrations** > **OAuth**
3. Click **Add Client**
4. Enter a name for the client (e.g., "Monad Audit Logs")
5. Set **Grant Types** to **Client Credentials** only
6. Under **Roles**, assign a role that includes the **Audit > Audit > View** permission (e.g., the built-in `Audit View` role)
7. Click **Save**
8. Copy and securely store the **Client ID** and **Client Secret**

**Important**: Client Credentials grant in Genesys Cloud only works with the region it was created in. The Client ID and Client Secret must be used with the corresponding region identifier.

## 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 |
| ------- | ---- | -------- | ----------- |
| Region | string | Yes | The Genesys Cloud region where your organization is hosted. Options: `us-east-1`, `us-west-2`, `ca-central-1`, `eu-west-1`, `eu-west-2`, `eu-central-1`, `ap-southeast-2`, `ap-northeast-1`, `ap-south-1`, `ap-northeast-2`, `sa-east-1`, `me-central-1`. |
| Backfill Start Time | string | No | The date to start fetching audit logs from in RFC3339 format (e.g., `2024-01-01T00:00:00Z`). If not specified, the connector will fetch logs from the time it is created on a pipeline. Maximum lookback is limited to 14 days by the Genesys Cloud realtime audit API. |
| Use Synthetic Data | boolean | No | Generates demo audit logs for testing without connecting to Genesys Cloud. Useful for testing configuration without credentials. |
| 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 from your Genesys Cloud Client Credentials application. |
| Client Secret | string | Yes | OAuth2 Client Secret from your Genesys Cloud Client Credentials application. |

## Rate Limits

Genesys Cloud implements rate limiting on API requests. The specific rate limits for the audit API endpoint may vary based on your organization's subscription tier. For current rate limit information, see the [Genesys Cloud Platform Rate Limits documentation](https://developer.genesys.cloud/platform/api/rate-limits).

The connector implements automatic retry logic with exponential backoff to handle rate limit responses gracefully.

## Troubleshooting

### Common Issues

#### 1. Authentication Failures (401 Unauthorized / invalid_client)

**Symptoms**: Error message "invalid_client" or 401 Unauthorized when attempting to connect

**Causes**:

- Wrong region selected for the credentials
- Client ID or Client Secret is incorrect
- Client Credentials grant has been deleted or revoked
- Credentials contain extra whitespace

**Solutions**:

- Verify the region matches where the OAuth client was created
- Double-check that the Client ID and Client Secret are correct and properly copied (no leading/trailing spaces)
- Check that the Client Credentials grant still exists in **Admin** > **Integrations** > **OAuth**
- Regenerate the Client Secret if it may have been compromised, and update Monad with the new value
- Confirm your Genesys Cloud login URL matches the region's expected login host (see Region Mapping table above)

#### 2. Permission Denied (403 Forbidden)

**Symptoms**: Error message indicates insufficient permissions or forbidden access

**Causes**:

- OAuth client role does not have the `audits:audit:view` permission
- Role has been modified and lost the required permission

**Solutions**:

- In Genesys Cloud, navigate to **Admin** > **Integrations** > **OAuth**
- Select your Client Credentials application
- Under **Roles**, verify that the assigned role includes the **Audit > Audit > View** permission
- If using a custom role, ensure the `audits:audit:view` permission is explicitly granted
- If using the built-in `Audit View` role, confirm it still exists and has the required permission

#### 3. No Audit Logs Appearing

**Symptoms**: Connector runs successfully but no audit logs are collected

**Causes**:

- No audit events occurred during the specified time window
- `Backfill Start Time` is set to a recent time (logs are only generated as events occur)
- Audit logging may not be enabled for your organization

**Solutions**:

- On the first sync without a `Backfill Start Time`, the connector fetches logs from now
- To see historical logs, set `Backfill Start Time` to an earlier date (within the 14-day window)
- Verify that audit events are actually occurring in your Genesys Cloud organization
- Check that audit logging is enabled in your organization's settings
- If no logs appear after administrative actions, verify the role has the correct permissions

#### 4. Invalid Backfill Start Time

**Symptoms**: Validation error about backfill time format

**Causes**:

- Date not in RFC3339 format
- Invalid date/time values
- Timestamp in the future
- Date is more than 14 days in the past (beyond API's maximum lookback)

**Solutions**:

- Use RFC3339 format with timezone: `2024-01-01T00:00:00Z` (UTC) or `2024-01-01T00:00:00-05:00` (with offset)
- Verify the date is valid and not in the future
- Backfill time cannot be more than 14 days before the current date
- The connector will automatically cap the lookback to 14 days if you specify an older date

#### 5. "Wrong Region" Errors During Connection Test

**Symptoms**: Connection test fails with authentication or invalid_client errors

**Causes**:

- Region selected in configuration does not match the region where the Client Credentials grant was created
- Each OAuth client is tied to a single region in Genesys Cloud

**Solutions**:

- Verify your login URL and cross-reference with the Region Mapping table
- Ensure the `Region` field matches the region where you created the OAuth client
- If you created the client in a different region, you must either recreate it in the correct region or create a new client with credentials tied to that region
- Note: One OAuth client per region — if you need to monitor multiple regions, you will need multiple client credentials, one for each region

## Related Articles

- [Genesys Cloud API Documentation](https://developer.genesys.cloud/apis/rest/)
- [Genesys Cloud OAuth Authentication](https://developer.genesys.cloud/platform/authentication/oauth-2-client-credentials-flow)
- [Genesys Cloud Audit API](https://developer.genesys.cloud/apis/rest/v2/audit_logs)
- [Genesys Cloud Platform Rate Limits](https://developer.genesys.cloud/platform/api/rate-limits)

## Sample Record

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userHomeOrgId": "550e8400-e29b-41d4-a716-446655440001",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "selfUri": "/api/v2/users/550e8400-e29b-41d4-a716-446655440002"
  },
  "client": {
    "id": ""
  },
  "remoteIp": ["192.0.2.1"],
  "serviceName": "UserService",
  "level": "USER",
  "eventDate": "2024-03-15T14:30:45.123Z",
  "action": "Create",
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "name": "New Queue",
    "selfUri": "/api/v2/entities/550e8400-e29b-41d4-a716-446655440003"
  },
  "entityType": "Queue",
  "status": "SUCCESS",
  "application": "",
  "initiatingAction": {},
  "transactionInitiator": false,
  "propertyChanges": [],
  "context": {},
  "entityChanges": []
}
```