Skip to main content
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:
FieldDescription
timestampISO-8601 UTC timestamp of the event.
eventThe event type (provider.login, provider.login_failed, provider.refresh_failed, provider.revoked, identity.claimed, etc.)
providerThe external provider involved (e.g., github, openai).
connectionThe named connection used.
identityThe Identity Handle making the call.
principal_idThe 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: 
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:
ParameterDescription
limitNumber of events to return, clamped to the server maximum.
cursorCursor 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_secrets, 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.