Audit Logging
Audit logging in Swimlane Turbine records critical actions and events across the system, providing visibility for monitoring, security, and compliance. Audit logs can be retrieved using the API, and users can apply filters to narrow down the results based on account, tenant, and time range.
Understand the API Log Retrieval Endpoint
Audit logs in Swimlane are accessible via two endpoints:
- auditlogs Endpoint (Recommended): Provides enhanced log data, including pagination and the total number of logs.
- https://<region>.swimlane.app/api/public/audit/account/{account_id}/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z&pageNumber=1&pageSize=100
- logs Endpoint: Retrieves basic log data. Planned for deprecation.
- https://<region>.swimlane.app/api/account/{account_id}/tenant/{tenant_id}/logs
Only Account Admins can access the Audit Logs.
Key API Parameters
Below are the key parameters that users can specify in their API calls to filter and paginate the audit log results:
Parameter | Description |
|---|---|
{account_id} | The unique identifier for the account. Required for all API requests to fetch audit logs. |
{tenant_id} | The identifier for the tenant associated with the account. Required for both account-level and tenant-level log retrieval. |
fromdate (Optional) | The start date for retrieving logs, in ISO 8601 format. If not provided, the API will default to retrieving logs starting 7 days prior to the current date. Use this parameter in combination with todate to specify a time range. |
todate (Optional) | The end date for retrieving logs, in ISO 8601 format. If not provided, the API will retrieve logs up to the current date. Useful when combined with fromdate to define a specific time range for logs. |
pageNumber (Optional) | Used for pagination. Specifies the page number of results to retrieve. Defaults to 1. If pageNumber and pageSize exceed a combined result of 10,000 logs, a warning is triggered, and further logs are not retrieved. Note: Audit logs retrieved from Elastic are currently capped at a maximum of 10,000 entries. This means that if more than 10,000 logs exist for the specified time range, only the first 10,000 logs will be returned, and subsequent logs will not be included in the results. Users should apply narrower date ranges or additional filters to retrieve the complete set of logs. |
pageSize (Optional) | Specifies how many log entries to return per page. The default and maximum page size is 100. Attempting to specify a pageSize larger than 100 will return an error. Use this in combination with pageNumber to paginate results effectively. |
tenantList (Optional) | Lists specific tenants whose logs are to be retrieved. If not specified, logs for all tenants under the account are returned. Combining this with includeAccount provides flexibility in log retrieval. |
includeAccount (Optional) | Specifies whether to include account-level logs in the response. Accepts `true` to include account logs, or `false` to exclude them. The default value is 'true'. For example, setting includeAccount=true with tenantList will return logs for both the account and the tenants. |
Pagination: The API supports pagination with the `pageNumber` and `pageSize` parameters. Use `pageNumber` to navigate through the pages of results and `pageSize` to limit how many entries appear on each page. For example, to retrieve the second page of results with 50 entries per page, use the following request: GET https://<region>.swimlane.app/api/public/audit/account/{account_id}/tenant/{tenant_id}/auditlogs?pageNumber=2&pageSize=50
Data retention is limited to 7 days.
Error Handling
Common errors to be aware of:
- If you specify a pageSize larger than 100, the API will return an error. For example, GET https://<region>.swimlane.app/api/public/audit/account/{account_id}/tenant/{tenant_id}/auditlogs?pageSize=150.
- 400 Bad Request: Returned when required parameters (such as `account_id` or `tenant_id`) are missing or invalid.
- 403 Forbidden: Returned if the user does not have permission to access the requested logs.
- 500 Internal Server Error: Indicates a server-side issue. If this occurs, try the request again later.
- Elastic Cap Error: If you request more than 10,000 logs within a date range, the API will only return the first 10,000 logs and ignore the rest.
Authentication for Audit Log API
The Audit Log API in Swimlane Turbine supports authentication exclusively via Personal Access Tokens (PATs). Only account admins have access to this API.
Prerequisites:
- Ensure you have admin access to the Swimlane Turbine account.
- Generate a Personal Access Token (PAT) from your Swimlane account.
Step 1: Generate a Personal Access Token (PAT)
- Log in to Swimlane.
- Click on your Profile & User Settings in the top-right corner.
- Navigate to Personal Access Token.
- Click Generate New Token.
- Copy the token immediately, as it won't be visible again after closing the dialog.
Step 2: Authenticate and Retrieve Audit Logs Using cURL
To access the Audit Log API, use the following cURL request with your Personal Access Token (PAT):
Example cURL Request:
curl -X GET "https://<region>.swimlane.app/api/public/audit/account/{account_id}/auditlogs" \ -H "Private-Token: <your_personal_access_token>"- Replace <region> with your Swimlane instance’s region.
- Replace {account_id} with your account’s ID.
- Replace <your_personal_access_token> with your actual personal access token (PAT) used in the Private-Token header.
Audit Logs Implementation Examples
Scenario 1: Get log for the account and tenants
- Description: Retrieves logs when all query parameters are not provided. The API will return logs for the account and all tenants with default pagination.
- Example Request:
- GET https://hostname/api/public/audit/account/{account_id}/auditlogs
- Result: Logs are returned with default time range, pagination (page 1), and page size (100).
- Output Example:
{
"totalCount": 1250,
"next": "/auditlogs?pageNumber=2&pageSize=100",
"previous": null,
"auditlogs": [
{
"eventTime": "2024-10-28T08:41:48Z",
"user": "[email protected]",
"userId": "12345",
"category": "Playbook",
"actionType": "Create",
"description": "Admin created playbook 'Incident Response'",
"eventOutcome": "Success"
}
]
}Scenario 2: Get tenant logs for a specific time range
- Description: Retrieves logs when tenantList is specified and includeAccount is set to true. Filters are applied using fromdate and todate.
- Example Request:
- GET https://hostname/api/public/audit/account/{account_id}/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z&pageNumber=1&pageSize=100
- Result: Logs related to the specified tenants and time range are returned, with pagination details and totalCount.
- Output Example:
{
"totalCount": 4113,
"next": "/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z&pageNumber=2&pageSize=100",
"previous": null,
"auditlogs": [
{
"eventTime": "2024-10-07T08:41:48Z",
"user": "[email protected]",
"userId": "56789",
"category": "UserManagement",
"actionType": "Retrieve",
"description": "User read details for userId: 56789",
"eventOutcome": "Success"
}
]
}Scenario 3: Warning for Exceeding 10K Logs
- Description: Retrieves logs when pageSize and pageNumber multiply to exceed the 10,000 logs cap, triggering a warning message.
- Example Request:
- GET https://hostname/api/public/audit/account/{account_id}/auditlogs?pageNumber=101&pageSize=100
- Result: The API returns a warning indicating the limit of 10,000 logs has been exceeded.
- Output Example:
{
"error": {
"message": "Cannot retrieve more than 10,000 logs. Please apply narrower filters.",
"code": 400
}Scenario 4: Tenant log with no Account level logs
- Description: Retrieves logs when tenantList is specified and includeAccount is set to false. Remaining parameters are not specified.
- Example Request:
- GET https://hostname/api/public/audit/account/{account_id}/auditlogs?tenantList=tenantIdList&includeAccount=false
- Result: Only tenant-level logs are returned for the last 7 days.
- Output Example:
{
"totalCount": 532,
"next": "/auditlogs?tenantList=tenantIdList&pageNumber=2&pageSize=100",
"previous": null,
"auditlogs": [
{
"eventTime": "2024-10-20T08:41:48Z",
"user": "[email protected]",
"userId": "98765",
"category": "Record",
"actionType": "Update",
"description": "User updated record 'Incident-234'",
"eventOutcome": "Success"
}
]
}Scenario 5: Logs with Pagination and Missing Tenant Information
- Description: Retrieves logs when tenantList, fromDate, and toDate are missing, but pagination is defined.
- Example Request:
- GET https://hostname/api/public/audit/account/{account_id}/auditlogs?pageNumber=2&pageSize=100
- Result: Logs related to the account and tenants for the default time range are returned with the specified pagination.
- Output Example:
{
"totalCount": 750,
"next": "/auditlogs?pageNumber=3&pageSize=100",
"previous": "/auditlogs?pageNumber=1&pageSize=100",
"auditlogs": [
{
"eventTime": "2024-10-21T08:41:48Z",
"user": "[email protected]",
"userId": "23456",
"category": "AssetManagement",
"actionType": "Delete",
"description": "User deleted asset 'Laptop-001'",
"eventOutcome": "Success"
}
]
}Scenario 6: Logs with Date Range Filters and Missing Pagination
- Description: Retrieves logs when fromdate and todate are specified, but tenantList and pagination details are missing.
- Example Request:
- GET https://hostname/api/public/audit/account/{account_id}/auditlogs?fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z
- Result: All logs related to the account and tenants for the specified date range are returned.
- Output Example:
{
"totalCount": 1600,
"next": "/auditlogs?pageNumber=2&pageSize=100",
"previous": null,
"auditlogs": [
{
"eventTime": "2024-10-05T08:41:48Z",
"user": "[email protected]",
"userId": "87654",
"category": "Settings",
"actionType": "Read",
"description": "User read security settings",
"eventOutcome": "Success"
}
]
}Scenario 7: Logs with All Query Parameters Specified
- Description: Retrieves logs when all query parameters (tenantList, includeAccount, fromdate, todate, pageNumber, and pageSize) contain values.
- Example Request:
- GET https://hostname/api/public/audit/account/{account_id}/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-07T23:59:59Z&pageNumber=1&pageSize=100
- Result: Logs related to the account and tenants, filtered by the specified parameters, are returned with pagination details and total count.
- Output Example:
{
"totalCount": 4200,
"next": "/auditlogs?tenantList=tenantIdList&includeAccount=true&fromdate=2024-10-01T00:00:00Z&todate=2024-10-30T23:59:59Z&pageNumber=2&pageSize=100",
"previous": null,
"auditlogs": [
{
"eventTime": "2024-10-07T08:41:48Z",
"user": "[email protected]",
"userId": "12345",
"category": "Playbook",
"actionType": "Create",
"description": "Admin created playbook 'Incident Response'",
"eventOutcome": "Success"
}
]
}Use this table to further understand the event types logged in audit logs:
Depending on the event type, some fields may not be present.
Audit Logs | Definition |
|---|---|
EventTime | The date and time when the event occurred in ISO 8601 format. |
User | The unique identifier (email) of the authenticated user. If the event is triggered by the system or automation, the field will be "Null." |
UserId | The unique identifier (GUID) for the user. |
Category | Defines the functional areas, such as Settings, Applications, User Management, Record, Solutions, Playbook, UserManagement, Sensor, and AccountManagement. |
Description | A short description of the event, including what action was taken and what data was accessed or modified. |
TenantId | Any action performed under a specific tenant. |
AccountId | For account-level operations (user management) the AccountId is required. AccountId is not required when TenantId is provided. |
SourceIp | The IP address of the client/user. |
UserAgent | User-agent header responsible for making the request for non-system access. |
ActionType | Describes the type of action that occurred, such as Create, Update, Delete, Read, Login, Logout, and UserAction. |
Id | ID of the value being created, updated, deleted, or read, when available. |
NewValue | New field value if the change or addition is atomic. For model updates, the new updated model in JSON format. |
EventOutcome | Either "Success" or "Failure". |
The following table lists the event/action category and their details events/actions.
Event/Action Category | Action Type |
|---|---|
Login /Logout | Login /Logout via Email |
| Login /Logout via SAML/SSO |
| Failed login for normal and SSO users |
| MFA changes (for example, switching it off) |
| Failed MFA |
| Password changes |
| Force SSO login changes |
|
|
User Management | Create, update, delete -> users, groups and roles |
| Changes in groups and roles for a user |
| Permission changes on groups, roles |
| Enable and disable 2FA at user level |
| Exempt force SSO for user |
| Create and delete PAT token |
|
|
Playbook/solution | User created a playbook |
| User updated a playbook |
| User deleted a playbook |
| User triggered playbook runs |
| Create a playbook with a webhook |
| Create a playbook with a schedule |
| Create a playbook with a record action |
| Install a solution |
| Update a solution |
| Delete a solution |
| Import an SSP |
| Install a component |
| Enable disable playbooks |
| Update action |
| CRUD triggers |
|
|
Record (exclude data ingested by integrations or updated by playbooks) | Create a record |
| Read a record |
| Update a record |
| Delete a record |
|
|
Asset Management | Create an asset |
| Read an asset |
| Update an asset |
| Delete an asset |
|
|
Connectors | Install a connector |
| Update or upgrade connector |
| Delete a connector |
|
|
Webhooks | Create, update and delete webhooks |
|
|
Settings | Authentication configuration: CRUD of MFA, SAML settings |
| Enable and Disable SAML |
| Enable and Disable 2FA |
| Password settings update |
| Enable and Disable Directory services |
| Changes to login, authentication and password policy settings, proxy settings |
| Changes to advanced configuration settings |
| Email settings |
| Update tenant specific settings like tim zone , email , connector Key |
|
|
Tenant Management | Create a Tenant |
| Update tenant feature flags |
| Update tenant limit |
| Delete tenant |
| Revoke user access to a tenant |
|
|
Account Management | CRUD account |
| Update account feature flags |
|
|
Applications | Schedule reports |
| CRUD on report |
| CRUD on dashboard |
| CRUD on application |
| CRUD on workspace |
| Update application settings |
| CRUD correlation |
| Field level permission updates |
|
|
Remote Agents
| Update remote agents |
| Create agents |
| Delete agents |
Audit Log Category Examples
ActionType Example of a Read Audit Event
{
"EventTime": "2025-02-25T15:48:14.7436951Z",
"User": "[email protected]",
"UserId": "e89asd4c-v3as-4e5d-99f1-049c4cf0f902",
"Category": "User Management",
"LogSource": "api",
"LogType": "Audit",
"Description": "ABC DEF read application user e89asd4c-v3as-4e5d-99f1-049c4cf0f902",
"AccountId": "30ad6dcd-bd77-4f2d-bfea-baddb677261f",
"TenantId": "fd336516-khk0-4b92-853a-55748ea86248",
"SourceIp": "::ffff:10.64.85.159",
"UserAgent": "axios\/1.7.7",
"ActionType": "Read",
"Id": "e89edf4c-a4de-4e5d-99f1-049c4cf0f902",
"EventOutcome": "Success",
"Endpoint": "\/user\/authorize",
"IsAdmin": "True",
"AuthenticationType": "JWT"
}Category Example: Playbook
{
"EventTime": "2025-02-25T15:32:56.2203069Z",
"User": "[email protected]",
"UserId": "e89asd4c-v3as-4e5d-99f1-049c4cf0f902",
"Category": "Playbook",
"LogSource": "api",
"LogType": "Audit",
"Description": "ABC DEF deleted ingestion rule by application ID aH3Sk1eHoF0n03soC",
"AccountId": "30ad6dcd-bd77-4f2d-bfea-baddb677261f",
"TenantId": "fd336516-khk0-4b92-853a-55748ea86248",
"SourceIp": "8.23.564.38",
"UserAgent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit\/537.36 (KHTML, like Gecko) HeadlessChrome\/133.0.0.0 Safari\/537.36",
"ActionType": "Delete",
"EventOutcome": "Success",
"Endpoint": "\/app\/aH3Sk1eHoF0n03soC",
"IsAdmin": "True",
"AuthenticationType": "JWT"
}Create Remote Agents:
{
"EventTime": "2025-02-27T09:28:52.870Z",
"User": "[email protected]",
"UserId": "17ee487f-d79a-8s2h-b66b-bdd093952897",
"Category": "Node",
"Description": "[email protected] Updated node 67c02bb1b84d184e62d823e5",
"ActionType": "Update",
"Id": "67c02bb1b84d184e62d823e5",
"SourceIp": "8.23.564.38",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
"EventOutcome": "Success",
"Endpoint": "/v1/agents/67c02bb1b84d184e62d154e5",
"IsAdmin": true,
"AuthenticationType": "JWT"
}Update Remote Agents:
{
"EventTime": "2025-02-27T09:28:52.870Z",
"User": "[email protected]",
"UserId": "17ee487f-d79a-8s2h-b66b-bdd093952897",
"Category": "Node",
"Description": "[email protected] Updated node 67c02bb1b84d184e62d823e5",
"ActionType": "Update",
"Id": "67c02bb1b84d184e62d823e5",
"SourceIp": "8.23.564.38",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
"EventOutcome": "Success",
"Endpoint": "/v1/agents/67c02bb1b84d184e62d154e5",
"IsAdmin": true,
"AuthenticationType": "JWT"
}Delete Remote Agent:
{
"EventTime": "2025-02-26T15:50:18.714Z",
"User": "[email protected]",
"UserId": "17ee487f-d79a-8s2h-b66b-bdd093952897",
"Category": "Node",
"Description": "[email protected] Updated node 67c02bb1b84d184e62d823e5",
"ActionType": "Delete",
"Id": "67bf29f50ee4512d80126a3a",
"SourceIp": "8.23.564.38",
"UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
"EventOutcome": "Success",
"Endpoint": "/v1/agents/67c02bb1b84d184e62d154e5",
"IsAdmin": true,
"AuthenticationType": "JWT"
}Best Practices for Audit Log Retrieval
Follow these best practices to optimize your use of the Swimlane audit logging API and ensure you retrieve accurate, comprehensive data efficiently.
- Use Date Filters to Narrow the Scope: Always apply specific date filters using the fromdate and todate parameters to avoid retrieving unnecessary data and hitting the 10,000-log cap. Example:
- GET https://<region>.swimlane.app/api/account/{account_id}/tenant/{tenant_id}/auditlogs?fromdate=2024-01-01T00:00:00Z&todate=2024-01-07T23:59:59Z
- Leverage Pagination for Large Datasets: When retrieving a large number of logs, utilize the pageNumber and pageSize parameters to paginate through the results efficiently. The maximum page size is 100. Example:
- GET https://<region>.swimlane.app/api/account/{account_id}/tenant/{tenant_id}/auditlogs?pageNumber=2&pageSize=50
- Combine Filters to Optimize Performance: Combine filters such as fromdate, todate, tenantList, and includeAccount to retrieve only the most relevant logs, reducing unnecessary data retrieval and improving performance. Example:
- GET https://<region>.swimlane.app/api/account/{account_id}/tenant/{tenant_id}/auditlogs?fromdate=2024-01-01T00:00:00Z&todate=2024-01-03T23:59:59Z&tenantList=t1,t2&includeAccount=true
- Handle the 10,000 Log Cap: If you expect more than 10,000 logs within a specific date range, adjust your queries to avoid hitting the cap. Split your requests into smaller batches using narrower date ranges or more specific filters. Tip: Automate requests to retrieve logs in increments, such as by day or by hour, to ensure all data is collected.