Audit logging

Every mutating action in Stoa is recorded in the audit log: who did it, what they did, what resource it affected, when it happened, and the IP address it came from. The log is searchable and filterable. This page explains what gets logged, how to read it, and how to use it for compliance.

What gets logged

Stoa records an entry for every action that changes state. This includes:

• User and role changes: account creation, role assignments, account deletion.
• Knowledge base operations: create, update, delete, reindex, document upload, document delete.
• Agent operations: create, update, delete.
• Integration changes: directory (AD/LDAP) configuration updates, email server changes, webhook registration.
• Instruction and branding changes.
• Authentication events: sign-in and sign-out.

Read-only chat messages and routine queries are not in the audit log. They live in conversation history, which has its own retention. The audit log is for governance, not for replaying conversations.

Each entry captures:

• Actor: the user (name or email) who performed the action.
• Action: what happened.
• Resource: the type of resource, its identifier, and its name (for example, a specific knowledge base by name).
• Detail: a short human-readable description, including the reason on a failed action.
• Timestamp: when the action occurred, in UTC.
• Source IP: the address the request came from. Useful for spotting unusual access patterns.
• Result: success or failure.
• Request ID: a unique identifier for the underlying request, useful if you ever need to reference a specific event when working with support.

Reading the log

In the admin UI, open the user menu, choose System, and select the Audit tab. The page shows a paginated list of audit entries. From here you can:

• Search by free text.
• Filter by resource type.
• Refresh to pick up new entries while you're investigating.

The default view shows the most recent activity across the whole platform.

Retention

By default, Stoa retains audit entries for 90 days, then automatically removes anything older. Retention is configurable if your policy requires longer (or shorter), and a change to it takes effect immediately, no restart required.

WARNING

Before shortening retention, make sure you have an export workflow in place (see below). Once an entry has aged out, it's gone from the live log.

For long-term archival beyond the live retention window, schedule periodic exports and store them in your existing compliance archive. See Backups for related guidance on long-term storage.

Exporting for compliance

The full audit log can be exported as a streamed, line-delimited file, ready to be ingested into a SIEM, an evidence vault, or a compliance reporting tool. There isn't a dedicated export button in the admin UI today: this is something your technical team or delivery engineer runs for you as a one-off request, using the same access you sign in with. Ask for it whenever you need a date range exported for a review or a regulator request.

Common compliance use cases

A few real situations where the audit log earns its keep:

• GDPR access reviews. When a data subject asks "who accessed my information," filter the log by the relevant resource and produce a list of actors and timestamps.
• Regulator requests. When an auditor asks for evidence of control over a sensitive system, request an export for the relevant date range and hand it over.
• Internal investigations. When something has gone wrong (a leaked document, a deleted knowledge base, an unexplained role change), the audit log is the first place to look. The actor, action, resource, and IP are usually enough to reconstruct what happened.
• Periodic access reviews. Quarterly, export the log and confirm that admin-level actions were performed by people who were supposed to perform them.

Permissions

Only users whose role grants audit access can view the log. Even admins can't quietly clear it: deletes are not supported, only retention-based aging. If you need to lock the log down further, restrict audit viewing to a single compliance role. See Roles & permissions.

Next

• Roles & permissions for who can read audit entries.
• Backups for long-term archival of exported logs.
• System status to correlate status changes with admin actions.