# Audit Logs

Audit logs record every significant action taken in your AccessIQ tenant, providing a complete trail of who did what and when. Every event is published asynchronously via an internal event pipeline, ensuring zero impact on request latency even during bulk operations.

## What Gets Logged

Audit logs capture actions across all areas of AccessIQ:

| Category          | Example events                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Users             | User created, updated, activated, deactivated, deleted (with full association cleanup -- org memberships, roles, credentials cascade-removed)     |
| Authentication    | Login success, login failure, MFA enabled/disabled, password changed                                                                              |
| Organizations     | Organization created, user added/removed, role changed                                                                                            |
| Applications      | App registered, credentials rotated, app deleted (cascade soft-delete of assignments, permissions, and overrides)                                 |
| Feature flags     | Flag created, value changed, targeting rule updated, org override added                                                                           |
| Security settings | Password policy changed, MFA requirement updated, session settings changed                                                                        |
| Admin actions     | Admin role granted/revoked, tenant settings changed                                                                                               |
| Impersonation     | Impersonation started (admin ID, target user, reason, org context), impersonation ended (auto-terminated after 30 min or when new session starts) |

## Viewing Audit Logs

1. Go to **Audit & Monitoring > Audit Logs**.
2. Browse the chronological list of events. Results are paginated -- use the controls at the bottom to navigate between pages or change the page size.

Each event includes:

| Field         | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| Timestamp     | When the action occurred                                               |
| Actor         | Who performed the action (user email or system)                        |
| Action        | What was done (e.g., `user.created`, `flag.updated`)                   |
| Resource type | The kind of object affected (e.g., User, Role, Flag)                   |
| Resource      | The specific resource ID or name                                       |
| Status        | Whether the action succeeded, failed, or produced a warning            |
| Risk score    | A numeric score indicating the security risk level (Low, Medium, High) |
| IP address    | Source IP of the request                                               |
| Details       | Additional context including old values, new values, and metadata      |

## Filtering

Click the **Filters** button in the top-right corner to open the filter panel. Available filters:

| Filter        | Description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| Date range    | Set a custom start date and end date to narrow events to a specific time window |
| User ID       | Search by the ID of the user who performed the action                           |
| Organization  | Filter events to a specific organization                                        |
| Action        | Filter by action type (e.g., `user.created`, `role.assigned`, `user.login`)     |
| Resource type | Filter by the type of resource affected                                         |
| Status        | Filter by outcome: Success, Failure, or Warning                                 |

Click **Apply Filters** to update the results. Click **Clear Filters** to reset all filters and return to the full log.

## Common Investigation Workflows

### How to find out who changed a user's role

1. Go to **Audit & Monitoring > Audit Logs**.
2. Click **Filters** to open the filter panel.
3. Set **Action** to `role.assigned` or `role.revoked`.
4. If you know the affected user, enter their user ID in the **User ID** field.
5. Set a **Date range** that covers the period of interest.
6. Click **Apply Filters**.
7. Review the matching events. Each entry shows the actor (who made the change), the target user, the role that was granted or revoked, and the timestamp.

### How to investigate failed login attempts

1. Go to **Audit & Monitoring > Audit Logs**.
2. Click **Filters**.
3. Set **Action** to `user.login`.
4. Set **Status** to **Failure**.
5. Set the **Date range** to the period you want to investigate.
6. Click **Apply Filters**.
7. Review the results. Each failed login entry shows the user email, the IP address of the request, and a risk score. Look for patterns such as repeated failures from the same IP address, which may indicate a brute-force attempt, or failures across many accounts from a single source.

### How to review impersonation sessions

1. Go to **Audit & Monitoring > Audit Logs**.
2. Click **Filters**.
3. Set **Action** to `impersonation.started` to see all impersonation sessions that were initiated.
4. Click **Apply Filters**.
5. Each impersonation event shows: the admin who initiated the session, the target user being impersonated, the stated reason, and the organization context.
6. To see when impersonation sessions ended, change the **Action** filter to `impersonation.ended` and apply again. Impersonation sessions are auto-terminated after 30 minutes or when a new session starts.

### How to track application access changes

1. Go to **Audit & Monitoring > Audit Logs**.
2. Click **Filters**.
3. Set **Resource type** to the application or permission resource you are investigating.
4. Click **Apply Filters**.
5. Look for events with actions like app deletion, permission changes, or credential rotation. When an application is deleted, the audit log records cascade soft-deletes of associated assignments, permissions, and overrides. Similarly, when a user is deleted, cascade cleanup of org memberships, roles, and credentials is logged.

## Real-Time Audit Streaming

For continuous monitoring without manual log review, set up audit streaming to push events to external systems in real time.

1. Go to **Audit & Monitoring > Audit Streaming**.
2. Click **Create Stream**.
3. Enter a name for the stream (e.g., "Security SIEM" or "Compliance Webhook").
4. Select the destination type -- **Webhook** is available for sending events to any HTTP endpoint.
5. Enter the destination URL.
6. Under **Event Filters**, select which event types to stream. Available events include `user.login`, `user.logout`, `user.created`, `user.updated`, `user.deleted`, `role.assigned`, `role.revoked`, `policy.created`, `policy.updated`, `mfa.enabled`, `mfa.disabled`, `session.revoked`, `invitation.sent`, and `invitation.accepted`.
7. Click **Save**.
8. Use the **Test Connection** button to verify the destination is reachable and receiving events correctly.

You can create multiple streams with different event filters to route specific categories to different systems. For example, send authentication events to a SIEM and user management events to an internal compliance tool.

## Exporting Audit Logs

1. Apply filters to select the events you need.
2. Click **Export CSV** to download a comma-separated file, or **Export JSON** for a structured JSON file.
3. Exports include up to 1,000 events matching your current filters. For larger exports, narrow the date range and export in batches, or use audit streaming for continuous data collection.

## Retention

| Plan         | Retention period             |
| ------------ | ---------------------------- |
| Starter      | 30 days                      |
| Professional | 1 year                       |
| Enterprise   | Configurable (up to 7 years) |

## Audit & Compliance Coverage

The following diagram shows how actions in your tenant are captured, stored, and made available for compliance reporting and review.

```mermaid
flowchart LR
    subgraph Tracked Actions
        A1[User & Role Changes]
        A2[Logins & MFA Events]
        A3[App & Permission Changes]
        A4[Security Policy Updates]
        A5[Impersonation Sessions]
    end

    subgraph Audit Pipeline
        B1[Event Captured\nwith Actor · Timestamp · Details]
        B2[Risk Score Assigned\nLow · Medium · High]
    end

    subgraph Storage & Retention
        C1[Starter — 30 days]
        C2[Professional — 1 year]
        C3[Enterprise — up to 7 years]
    end

    subgraph Reporting & Access
        D1[Tenant Admins\nDashboard & Filters]
        D2[Compliance Reports\nPDF · CSV · JSON]
        D3[Real-Time Streaming\nSIEM & Webhooks]
        D4[Export & Archive\nLong-Term Evidence]
    end

    subgraph Governance & Review
        E1[SOC 2 · GDPR\nHIPAA · ISO 27001]
        E2[Scheduled Reviews\nWeekly · Monthly]
        E3[Auditor Evidence\nTamper-Proof Archives]
    end

    A1 & A2 & A3 & A4 & A5 --> B1 --> B2
    B2 --> C1 & C2 & C3
    C1 & C2 & C3 --> D1 & D2 & D3 & D4
    D1 & D2 & D3 & D4 --> E1 & E2 & E3
```

## Using Audit Logs for Compliance

Audit logs support compliance requirements such as:

* **SOC 2** -- Demonstrate access controls and change tracking across your tenant.
* **GDPR** -- Track who accessed or modified personal data. Use the User ID filter to produce a complete history of actions related to a specific individual.
* **HIPAA** -- Maintain records of access to protected information. The PHI access filter can isolate events involving protected health information.
* **ISO 27001** -- Provide evidence of information security controls, including role changes, policy updates, and security setting modifications.

## Best Practices for Compliance Reviews

* **Establish a review cadence.** Review audit logs at least weekly for unexpected changes, especially to security settings and admin roles. Monthly full reviews are recommended for compliance-regulated environments.
* **Set up real-time streaming for critical events.** Configure audit streams for high-severity events such as admin role changes, security policy modifications, impersonation sessions, and failed login spikes. This ensures your security team is alerted immediately rather than discovering issues during periodic reviews.
* **Export and archive regularly.** Export logs periodically for long-term storage beyond your plan's retention period. Store exports in a tamper-proof location such as an immutable object store.
* **Document your review process.** For SOC 2 and ISO 27001 audits, maintain records of who reviewed the logs, when, and what actions were taken as a result.
* **Use filters to build repeatable reports.** For recurring compliance checks, document the filter combinations you use so reviews are consistent each time. For example, a monthly access review might always filter for `role.assigned` and `role.revoked` events within the past 30 days.
* **Cross-reference with user lifecycle events.** When investigating a security incident, combine authentication event filters with user management filters to build a complete timeline of what happened before and after the incident.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://accessiq.gitbook.io/accessiq-docs/audit-and-compliance/audit-logs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.