Audit Logs

Overview

Alter Vault automatically logs all activity across the application, including token access, connection changes, API calls, and admin actions. Logs can be viewed, filtered, and exported from the Developer Portal and Wallet Dashboard.

Automatic

All activity is logged automatically with no code changes needed

Searchable

Filter by provider, user, actor, date, and event type

Exportable

Export as CSV for compliance reporting

Viewing Audit Logs in the Developer Portal

Go to Audit Logs in the Developer Portal sidebar to see all activity across the application.

Filtering

Use the filter bar to narrow down results:

Event type: Token access, connection changes, API calls, admin actions
Provider: Google, Slack, GitHub, Sentry, etc.
User: Search by user ID or email
Actor: Filter by AI agent name
Date range: Pick a custom time window

Detail View

Click any audit log entry to see full details:

Who made the request (user, AI agent, or admin)
What was accessed (provider, endpoint, scopes)
When it happened (timestamp with timezone)
The outcome (success, policy denial, error)
Request context (reason, run ID, thread ID)

Exporting

Export filtered audit logs as CSV for compliance reporting:

Apply the desired filters
Click Export
Download the CSV file

Viewing Activity in the Wallet Dashboard

End users can view their own activity in the Wallet Dashboard under Activity:

Which apps accessed their data
Which AI agents made API calls on their behalf
When connections were created or revoked
Recent token access history

This gives end users transparency into how their connected accounts are being used.

What Gets Logged

Alter Vault logs six categories of events automatically:

Token & Secret Access

Every time a credential is retrieved via vault.request() — both OAuth tokens and managed secrets. Includes provider, scopes, policy decision, actor, reason, and request intent (HTTP method and URL the caller plans to use).

Connection Lifecycle

Connection created, updated, revoked, re-authenticated, or expired.

API Calls

Every external API call made through the SDK. Includes HTTP method, URL, response status, and latency.

Developer Portal Actions

Admin actions like creating apps, configuring providers, updating policies, and rotating API keys.

End User Activity

Wallet Dashboard activity like login, logout, viewing connections, and revoking access.

Audit Log Fields

Every audit log entry includes a standard set of fields:

Field	Description
Timestamp	When the action occurred (ISO 8601, UTC)
Action	Type of event (e.g., credential retrieved, connection authorized, access denied)
Action type	Category: `read`, `write`, or `error`
Provider	OAuth provider or managed secret service
Actor	Who made the request — backend service, AI agent (including MCP-connected agents), or end user
Reason	Developer-provided explanation of why the action was taken
Policy decision	`ALLOW` or `DENY`, with the specific rule that triggered a denial
HTTP method & URL	The API call the credential was used for
Status code	Response status from the target API
Latency	Round-trip time for the API call (milliseconds)
Trace ID	Correlation ID for distributed tracing (W3C traceparent)

Adding Context to Audit Logs

Add a reason parameter to API calls for richer audit context:

response = await vault.request(
    HttpMethod.GET,
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    grant_id="GRANT_ID",  # grant_id (UUID)
    reason="Syncing calendar for weekly digest email",
)

The reason appears in the audit log detail view, making it easy to understand why each API call was made.

AI Agent Tracking

When using AI agents, audit logs automatically capture actor context:

from alter_sdk import AlterVault, HttpMethod

vault = AlterVault(
    api_key="alter_key_...",
    caller="email-assistant-v2",
)

response = await vault.request(
    HttpMethod.GET,
    "https://gmail.googleapis.com/gmail/v1/users/me/messages",
    grant_id="GRANT_ID",  # grant_id (UUID)
    context={"tool": "read_emails", "agent": "email-assistant-v2"},
    reason="Reading emails for daily digest",
)

In the Developer Portal, you can filter audit logs by caller to see exactly what each agent did and when. Registered callers also appear in the Agents tab. See the Python SDK Overview for setup details.

Caller and Context Fields

Set once at SDK initialization:

Field	Required	Description	Example
Caller	No	Unique identifier for this SDK instance (registered in the caller registry)	`"email-assistant-v2"`

Set per request (written to each audit log row as context JSONB):

Field	Type	Description	Example
context	`dict[str, str]`	Per-request identity and execution details	`{"tool": "read_calendar", "agent": "cursor"}`

The context dict must use string keys and string values. The SDK validates the shape before sending: at most 20 keys, no key longer than 64 characters, no value longer than 512 characters, and the total JSON-encoded payload must fit in 4 KB. Violations raise AlterValueError. Common context keys include tool (which tool is being invoked), agent (upstream AI agent), run_id, thread_id, parent_tool, and tool_call_id. The FastMCP integration and LangChain integration packages populate these automatically. These fields let you trace exactly which caller, in which execution context, made each credential access.

Managed Secret Audit Logging

Managed secret access is logged with the same detail as OAuth token access:

Credential retrieved — a managed secret was used via vault.request()
Access denied — access was blocked by a policy violation (time, IP, or TTL)
Secret stored — a new secret was stored in the Developer Portal
Secret rotated — a secret value was replaced
Secret revoked — a secret was deleted

All the same filtering, export, and actor tracking features apply. In the Developer Portal, filter by provider to see all activity for a specific managed secret.

Policy Decisions in Audit Logs

Every credential access logs the policy evaluation result:

Allowed — which policies were checked and passed
Denied — which specific rule failed (time restriction, IP allowlist, or connection TTL)
Policy context — the policy configuration that was evaluated

This makes it easy to investigate access patterns, debug policy violations, and demonstrate compliance during audits. See the Security Policies guide for configuring policies.

Trace Context

Every audit log entry includes a trace_id field that correlates with the request’s correlation ID. When a W3C traceparent header is sent, the trace ID and span ID from the distributed tracing system (OpenTelemetry, Zipkin, AWS X-Ray) are automatically captured. This enables linking audit log entries directly to traces in the observability platform.

Compliance

Audit logs are designed for compliance out of the box:

Standard	What Audit Logs Provide
SOC 2	Evidence of access controls, change management, and monitoring
GDPR	Complete data access records for right-of-access requests
HIPAA	Full audit trail of PHI access through OAuth grants and managed secrets

Common Compliance Queries

Question	How to Find It
”Who accessed this user’s data?”	Filter by connection ID or end user identifier
”What did this AI agent do?”	Filter by actor name or actor identifier
”Were there any policy violations?”	Filter by event type → policy denial
”When was this credential last used?”	Filter by provider + sort by timestamp
”What APIs were called with this secret?”	Filter by connection ID → view API call logs

Data Retention

The default retention period is 12 months. Each audit log entry includes a retention_until field and an optional legal_hold flag. Records under legal hold are never deleted regardless of retention policy. Retention can be extended per-record for regulatory requirements (e.g., 6 years for HIPAA). A daily background job enforces the retention policy by deleting expired records. Contact support for custom archival policies.

Next Steps

Actor Tracking

Set up AI agent tracking in the Python SDK

Security Policies

Configure access policies that are enforced and logged

Developer Portal

View audit logs in the portal

Managed Secrets

Managed secret audit logging details

Getting Started

Guides

SDKs

Identity Providers

OAuth Providers

Managed Secret Providers

Reference

Overview

Automatic

Searchable

Exportable

Viewing Audit Logs in the Developer Portal

Filtering

Detail View

Exporting

Viewing Activity in the Wallet Dashboard

What Gets Logged

Audit Log Fields

Adding Context to Audit Logs

AI Agent Tracking

Caller and Context Fields

Managed Secret Audit Logging

Policy Decisions in Audit Logs

Trace Context

Compliance

Common Compliance Queries

Data Retention

Next Steps

Actor Tracking

Security Policies

Developer Portal

Managed Secrets

Getting Started

Guides

SDKs

Identity Providers

OAuth Providers

Managed Secret Providers

Reference

Documentation Index

​Overview

Automatic

Searchable

Exportable

​Viewing Audit Logs in the Developer Portal

​Filtering

​Detail View

​Exporting

​Viewing Activity in the Wallet Dashboard

​What Gets Logged

​Audit Log Fields

​Adding Context to Audit Logs

​AI Agent Tracking

​Caller and Context Fields

​Managed Secret Audit Logging

​Policy Decisions in Audit Logs

​Trace Context

​Compliance

​Common Compliance Queries

​Data Retention

​Next Steps

Actor Tracking

Security Policies

Developer Portal

Managed Secrets

Overview

Viewing Audit Logs in the Developer Portal

Filtering

Detail View

Exporting

Viewing Activity in the Wallet Dashboard

What Gets Logged

Audit Log Fields

Adding Context to Audit Logs

AI Agent Tracking

Caller and Context Fields

Managed Secret Audit Logging

Policy Decisions in Audit Logs

Trace Context

Compliance

Common Compliance Queries

Data Retention

Next Steps