# Serval Audit Logs Retrieves audit log events from [Serval](https://serval.com), an AI-powered IT service and access management platform. Events record who did what, when, from where, and with what result. They cover: - access requests, approvals, provisioning and deprovisioning - access reviews - access policy and role changes - sign-ins and failed sign-ins - workflow changes - API key activity Each event includes the actor, source IP and user agent, an outcome status (`STATUS_SUCCESS`, `STATUS_FAILURE`, `STATUS_DENIED`, `STATUS_ERROR`), a severity, and the actor's stated justification for privileged actions. **Sync Type: Incremental** ## Prerequisites - Organization admin access to Serval. - The data residency region your Serval organization was created in. Your sign-in address tells you which: `app.serval.com` is **United States**, `app.eu1.serval.com` is **European Union**. - An **organization-scoped** Serval API key with the `org:audit` permission. Workspace-scoped keys can't read the audit log. - The key's **Teams list must be left empty**. A team-restricted key cannot read audit logs, even with the right permission. ## Authentication Serval API keys come as a **Client ID** and **Client Secret**. Monad exchanges them for a short-lived access token using the OAuth 2.0 client-credentials flow and refreshes the token automatically. To create a key: 1. Sign in to Serval as an organization admin and open the [API settings page](https://app.serval.com/admin/settings). 2. Create a new API key scoped to the **organization**, not to a workspace. 3. Grant it the `org:audit` permission. No other permissions are needed. 4. Leave the **Teams** list empty. A team-restricted key cannot read audit logs. 5. Copy the **Client ID** and **Client Secret**. Store the secret in your secret manager. Serval requires every API key to carry an expiry date, so this credential **will** stop working on the date you set. Before it expires, create a replacement key with the same scope, update the input, then revoke the old one. Once a key expires the token exchange fails and the sync stops. See Serval's [Token types and permissions](https://docs.serval.com/sections/api-reference/authorization) and [Create Token](https://docs.serval.com/api-reference/auth-api/create-token) docs. ## 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 Serval data residency region your organization was created in: **United States** or **European Union**. Determines which API base URL is used. Defaults to United States. | | Client ID | string | Yes | Client ID of a Serval organization-scoped API key with the `org:audit` permission. | | Backfill Start Time | date | No | The date and time to start fetching events from, chosen with the date picker. Serval keeps 90 days of audit logs, so anything older is unavailable. If not specified, the first sync starts from now and all later syncs are incremental. The late-event re-read never goes earlier than this starting point (see [Late events](#late-events)). | | API Rate Limit | object | No | Maximum outbound request rate to the Serval API (`rate` + `unit`). Serval publishes no rate ceiling for this endpoint, so the default is **1 request/second** and the cap is 10 requests/second. | | Use Synthetic Data | boolean | No | Generate synthetic demo data instead of connecting to Serval. Useful for pipeline testing. | ### Secrets | Secret | Type | Required | Description | |---------|------|----------|-------------| | Client Secret | string | Yes | Client secret of the same Serval API key. Monad exchanges the client ID and secret for a short-lived access token. | ## Setup Walk-through 1. In Serval, create an organization-scoped API key with `org:audit` and copy its Client ID and Client Secret (see [Authentication](#authentication)). 2. In Monad, create a new input and select **Serval → Audit Logs**. 3. Paste the **Client ID** and **Client Secret**. 4. Select the **Region** your Serval organization was created in. 5. Optionally set **Backfill Start Time** to pull up to 90 days of history. 6. Attach the input to a pipeline and save. ### Late events Serval can store an event up to a day after its timestamp, which places it behind a watermark that has already moved on. To catch these, every 12 hours a sync widens its window to re-read the previous 48 hours. Monad remembers the IDs of events it has sent in that 48-hour span and only sends events it hasn't seen, so the re-read adds late events without duplicating others. The re-read never reaches earlier than where the input first started: the **Backfill Start Time** if one was set when the input was created, otherwise the time of the first sync. This starting point is saved on the first sync, so changing the backfill time later doesn't move it. ### Filtering Serval returns all event types. Filter by `eventType`, `outcome.status` or `severity` in your pipeline with a transform or condition. For example, keep `outcome.status == "STATUS_DENIED"` for access-denied alerting, or drop `SEVERITY_DEBUG` and `SEVERITY_TRACE` operational events. ## Troubleshooting ### Common Issues - **`oauth2: cannot fetch token: 401 Unauthorized`**: the Client ID or Client Secret is wrong, or the key has been revoked or has reached its expiry date. Serval keys always expire, so check this first. Create a new key and update the input. - **`403` / `permission_denied`**: the key lacks `org:audit`, is workspace-scoped, or has one or more **Teams** assigned. Create an organization-scoped key with `org:audit` and an empty Teams list. - **`429` on token requests**: Serval allows 60 token requests per minute per IP. Monad caches each token until it expires, so this usually means many inputs share one egress IP. Monad retries the token request a few times with backoff. If it still gets a `429`, the sync fails, and the next sync re-reads its time window from the start, skipping events already sent, so no events are lost or duplicated. - **Test connection fails**: the test requests one event from the last hour, so it checks the credentials, the `org:audit` permission and the Region's API address. It succeeds even if no events exist in that hour. A failure returns the same `401` / `403` errors described above. - **`audit logs pagination stalled: nextPageToken ... repeated`**: Serval returned the same page token twice. The sync stops instead of advancing past unread pages and retries on its next run. If it keeps happening, contact Serval support. - **Connection succeeds but no events arrive**: check the **Region**. Serval's US and EU regions are fully isolated, so a key from one region reaches none of the other's data and returns an empty result rather than an error. - **Backfill returns nothing older than 90 days**: expected. Serval retains audit logs for 90 days. - **Newest events missing**: expected. The sync window ends one minute in the past, and those events arrive on the next sync. - **An older event arrives hours after it happened**: expected. Serval stored it late, and the 12-hourly re-read of the last 48 hours picked it up (see [Late events](#late-events)). ## Related Articles - [Serval List Audit Logs API reference](https://docs.serval.com/api-reference/audit-log-api/list-audit-logs) - [Serval Create Token](https://docs.serval.com/api-reference/auth-api/create-token) - [Serval token types and permissions](https://docs.serval.com/sections/api-reference/authorization) - [Serval data residency](https://docs.serval.com/sections/documentation/platform/data-residency)