> ## Documentation Index
> Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit events

> How Authsome records security events using an SQLite-backed storage model.

Authsome keeps an append-only event log for sensitive actions. In the current release, it writes audit events to an SQLite-backed storage managed by the local daemon, moving away from the old flat-file `audit.log`.

## Overview

The Audit log tracks:

* **External AuditEvents**: Outbound HTTP calls an agent makes through the proxy to a third-party API (for example, `api.github.com`).
* **Internal AuditEvents**: Credential lifecycle operations (login, logout, token refresh, revocation) and auth flow steps.

**The Server is the Source of Truth:**
The local Authsome daemon acts as the central source of truth. All proxy instances (sidecars) ship their events asynchronously to the daemon via the `POST /audit/events` endpoint. The proxy itself does not write to local files.

## Event Schema

Every `AuditEvent` requires two actor fields:

* `identity`: The cryptographic agent Handle making the request.
* `principal_id`: The human or team Principal that owns the Vault.

Common fields included:

| Field          | Description                                                                                                                         |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp`    | ISO-8601 UTC timestamp of the event.                                                                                                |
| `event`        | The event type (`provider.login`, `provider.login_failed`, `provider.refresh_failed`, `provider.revoked`, `identity.claimed`, etc.) |
| `provider`     | The external provider involved (e.g., `github`, `openai`).                                                                          |
| `connection`   | The named connection used.                                                                                                          |
| `identity`     | The Identity Handle making the call.                                                                                                |
| `principal_id` | The PrincipalId resolved by the server.                                                                                             |

## Dashboard and Admin Access

Authsome includes an **Admin Audit Dashboard**, served natively by the daemon (at `/audit`).

* Principals with the `admin` role can view all events across the deployment.
* Principals with the `user` role may only view events relevant to their own PrincipalId.

## Reading the Log

You can view the audit events directly from the CLI or query the daemon:

```bash theme={null}
authsome log              # Print recent audit events
authsome log --json       # Output JSON format
```

### User-scoped access

`GET /api/audit/events` is role-aware. Admin principals can review the global audit log.
Non-admin principals receive only events scoped to their own principal, including their
claimed identities, vault, providers, and credential lifecycle activity.

Supported query parameters:

| Parameter | Description                                                |
| --------- | ---------------------------------------------------------- |
| `limit`   | Number of events to return, clamped to the server maximum. |
| `cursor`  | Cursor returned by the previous page.                      |

Results are sorted newest-first and include `next_cursor` when another page is available.

## Privacy and Secrets

**What the log contains:**

* Timestamps for every significant action.
* Provider and connection names.
* Event types, identity handles, and principal IDs.
* Outcome metadata (like `status: "failure"` on failed logins).

**What the log does NOT contain:**

* Access tokens, refresh tokens, API keys, `client_secret`s, or any other secret values.
* Decrypted credential records.
* Request payloads passed through the proxy.

If you ever find a secret in the audit output, that is a bug. Report it through [Responsible disclosure](/security/disclosure).