# Audit logs

> View and filter Botyard audit logs: who can read them, the event model, Runtime Vault secret events, and how to search events in the app or through the API.

Canonical URL: https://docs.botyard.io/docs/audit-logs

Botyard audit logs give organization owners a searchable account of security and product events.
They are designed for accountability: who or what acted, what resource was affected, when it
happened, and which trace, request, conversation, or workforce task can help explain the event.

## View audit logs

1. Sign in to [app.botyard.io](https://app.botyard.io).
2. Open **User menu** › **Settings** › **Audit log**.
3. Filter by domain, severity, event type, actor, or text search.
4. Open an event to inspect its structured details.

By default, only organization owners can read audit logs. Members and viewers can't. This is
intentional: audit events can include organization-wide activity across users, bots, API keys,
secrets, and runtime actions.

## Event model

Each audit event has a stable envelope:

| Field       | Purpose                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Domain      | Product area: `secrets`, `auth`, `admin`, `privacy`, `bot_runtime`, `billing`, `provisioning`, `integration`, or `bot_device`. |
| Event type  | Stable dotted name, such as `secrets.lease.granted`.                                                                           |
| Severity    | `trace`, `info`, `warning`, or `critical`.                                                                                     |
| Actor       | User, bot, or API key responsible for the event.                                                                               |
| Resource    | Primary object affected by the event.                                                                                          |
| Target      | Secondary object, when useful.                                                                                                 |
| Context IDs | Request, trace, conversation, or workforce task identifiers.                                                                   |
| Content     | Typed event-specific metadata.                                                                                                 |

Customer-visible audit events are separated from internal-only events. Event metadata and
content are sanitized by producers and must not include secrets or raw payloads.

## Secrets and Runtime Vault events

Runtime Vault records these events in the `secrets` domain:

* lease requested, granted, denied, used, and expired
* secret expiry set or cleared
* vault entry value updated (the new value is never recorded)
* credential destination acknowledged, when an MCP server that sends Runtime Vault values in
  its request headers is pointed at a new endpoint
* exfiltration detected, redacted, and blocked

These events are how you see which bot asked for which secret, and what happened. Botyard
also keeps a lower-level secret access record for its own operations. That record isn't
available in the app or the API.

## Search and API access

The audit log API supports listing and structured search:

* `GET /v1/orgs/{org_id}/audit-events`
* `POST /v1/orgs/{org_id}/audit-events/search`

Use the search endpoint when you need filters. It accepts the shared Botyard filter DSL and can
filter on fields such as domain, event type, severity, actor IDs, resource IDs, conversation ID,
task ID, request ID, trace ID, and created time.

## Safety pattern

Botyard audit logs follow an **append-only accountability log** pattern. Producers write
structured, sanitized events with stable event names. Readers search the customer-visible event
stream. Sensitive payloads stay out of the log, while IDs and typed metadata preserve enough
context for investigation and compliance review.