Organization Audit Logs API on AuthOS Docs | Auth Operating System API and SDK Guides

Audit Log Endpoint Reference

Mon, 01 Jan 0001 00:00:00 +0000

Data Models

Audit Log Entry

{
  "id": "uuid",
  "organization_id": "uuid",
  "actor_id": "uuid",
  "actor": {
    "id": "uuid",
    "email": "admin@acme.com"
  },
  "action": "service.created",
  "target_type": "service",
  "target_id": "service-uuid",
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0...",
  "success": true,
  "metadata": {
    "service_slug": "main-app",
    "service_name": "Main Application",
    "service_type": "web",
    "client_id": "client-uuid"
  },
  "created_at": "2025-01-15T10:30:00Z"
}

Audit Log Response with User

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "org-uuid",
  "actor_id": "user-uuid",
  "actor": {
    "id": "user-uuid",
    "email": "admin@acme.com"
  },
  "action": "service.created",
  "target_type": "service",
  "target_id": "service-uuid",
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  "success": true,
  "metadata": {
    "service_slug": "main-app",
    "service_name": "Main Application",
    "service_type": "web",
    "client_id": "client-uuid"
  },
  "created_at": "2025-01-15T10:30:00Z"
}

Pagination Info

{
  "page": 1,
  "limit": 50,
  "total": 1250,
  "total_pages": 25,
  "has_next": true,
  "has_prev": false
}

Audit Event Types

For a complete reference of all audit events including triggering actions and details payload schemas, see Audit Events Reference.

Querying and Filtering Audit Logs

Mon, 01 Jan 0001 00:00:00 +0000

The audit-log endpoint supports server-side filters for action, target type, and target ID. Use pagination for complete investigations. Filtering by actor, success, IP address, or date is not currently supported by the endpoint and must be applied to retrieved pages on the client.

Common Use Cases

Security Investigation

Scenario: Investigate suspicious activity after detecting an anomaly.

# 1. Find all actions by a specific user
curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?page=1&limit=100" \
  -H "Authorization: Bearer ..." | jq '.logs[] | select(.actor.email == "suspect@acme.com")'

# 2. Check for service deletions
curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?action=service.deleted" \
  -H "Authorization: Bearer ..."

# 3. Review failed actions
curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?page=1&limit=100" \
  -H "Authorization: Bearer ..." | jq '.logs[] | select(.success == false)'

# 4. Check actions from unusual IP
curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?page=1&limit=100" \
  -H "Authorization: Bearer ..." | jq '.logs[] | select(.ip_address == "suspicious.ip.address")'

Configuration Change Tracking

Scenario: Track changes to a specific service.

Audit Log Export and Integrations

Mon, 01 Jan 0001 00:00:00 +0000

Exports must paginate through the complete result set needed by the use case. Protect both the AuthOS bearer token and downstream collector credentials.

Common Use Cases

Compliance Evidence Export

Scenario: Export selected records for review within a SOC 2 control program. This export is not a SOC 2 report or certification and its coverage must be validated by the operator.

# 1. Export all security events
curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?page=1&limit=100" \
  -H "Authorization: Bearer ..." | \
  jq '.logs[] | select(.category == "Security")' > security_events.json

# 2. Export all user management events
curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?target_type=user" \
  -H "Authorization: Bearer ..." > user_management.json

# 3. Generate CSV report
curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?page=1&limit=1000" \
  -H "Authorization: Bearer ..." | \
  jq -r '.logs[] | [.created_at, .actor.email, .action, .target_type, .target_id, .success] | @csv' \
  > audit_report.csv

Integration Examples

Export to Splunk

#!/bin/bash
# Export audit logs to Splunk

ORG_SLUG="acme-corp"
AUTH_TOKEN="your-jwt-token"
SPLUNK_URL="https://splunk.example.com:8088/services/collector"
SPLUNK_TOKEN="your-splunk-hec-token"

# Fetch logs
logs=$(curl -s -X GET "https://sso.example.com/api/organizations/$ORG_SLUG/audit-log?limit=100" \
  -H "Authorization: Bearer $AUTH_TOKEN")

# Send to Splunk
echo "$logs" | jq -c '.logs[]' | while read log; do
  curl -X POST "$SPLUNK_URL" \
    -H "Authorization: Splunk $SPLUNK_TOKEN" \
    -d "{\"event\": $log, \"sourcetype\": \"sso_audit_log\"}"
done

Slack Notifications

// Node.js: Send critical audit events to Slack

const axios = require('axios');

const CRITICAL_EVENTS = [
  'service.deleted',
  'user.removed',
  'api_key.created',
  'api_key.deleted',
  'security.mfa.disabled'
];

async function pollAuditLogs() {
  const response = await axios.get(
    'https://sso.example.com/api/organizations/acme-corp/audit-log?limit=10',
    { headers: { Authorization: `Bearer ${process.env.SSO_JWT}` } }
  );

  for (const log of response.data.logs) {
    if (CRITICAL_EVENTS.includes(log.action)) {
      await sendSlackAlert(log);
    }
  }
}

async function sendSlackAlert(log) {
  await axios.post(process.env.SLACK_WEBHOOK_URL, {
    text: `=� Critical Action: ${log.action}`,
    attachments: [{
      color: 'danger',
      fields: [
        { title: 'Actor', value: log.actor.email, short: true },
        { title: 'Target', value: log.target_type, short: true },
        { title: 'Time', value: log.created_at, short: true },
        { title: 'IP', value: log.ip_address || 'N/A', short: true }
      ]
    }]
  });
}

// Poll every 5 minutes
setInterval(pollAuditLogs, 5 * 60 * 1000);

Python Report Generator

import requests
import csv
from datetime import datetime

SSO_API = 'https://sso.example.com'
ORG_SLUG = 'acme-corp'
AUTH_TOKEN = 'your-jwt-token'

def export_audit_logs_to_csv(output_file='audit_logs.csv'):
    """Export paginated audit records to CSV for operator review."""

    headers = {'Authorization': f'Bearer {AUTH_TOKEN}'}
    page = 1
    all_logs = []

    # Paginate through all logs
    while True:
        response = requests.get(
            f'{SSO_API}/api/organizations/{ORG_SLUG}/audit-log',
            params={'page': page, 'limit': 100},
            headers=headers
        )
        data = response.json()
        all_logs.extend(data['logs'])

        if not data['pagination']['has_next']:
            break
        page += 1

    # Write to CSV
    with open(output_file, 'w', newline='') as csvfile:
        fieldnames = ['timestamp', 'actor_email', 'action', 'target_type',
                      'target_id', 'success', 'ip_address']
        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

        writer.writeheader()
        for log in all_logs:
            writer.writerow({
                'timestamp': log['created_at'],
                'actor_email': log['actor']['email'],
                'action': log['action'],
                'target_type': log['target_type'],
                'target_id': log['target_id'],
                'success': log['success'],
                'ip_address': log.get('ip_address', 'N/A')
            })

    print(f'Exported {len(all_logs)} audit logs to {output_file}')

if __name__ == '__main__':
    export_audit_logs_to_csv()

Audit Log Compliance and Security

Mon, 01 Jan 0001 00:00:00 +0000

Security Considerations

Access Control:

Only owners and admins can view audit logs
API queries are intended to scope logs by organization; public cross-tenant coverage evidence is still being expanded
Deleted users still appear in logs (email preserved)
Platform owners cannot access organization audit logs (privacy)

Data Retention:

The API does not expose general deletion; verify actual database retention and cleanup behavior
Define retention based on applicable operational and legal requirements
Export logs regularly for archival
Logs survive organization deletion (platform-level cleanup required)

Sensitive Information:

Audit Log Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Start with the endpoint response, then verify the deployed release’s event coverage and the collection logic used by the consuming system.

Symptom guide

Symptom	Check	Resolution
401 response	Authorization header and token validity	Send a current organization-management JWT
403 response	Caller role	Use an organization owner or admin account
Expected record is absent	Event coverage, organization scope, action name, and collection time	Confirm the release emits that event and remove over-narrow filters
Filter returns no records	Exact action value and target-type/target-ID pairing	Load event types and use the returned value; pair target ID with target type
Export stops at 100 records	Pagination metadata	Continue until has_next is false
Actor, date, IP, or success filter seems ignored	Supported query parameters	Retrieve paginated records and apply those filters client-side
Details are incomplete	Event-specific schema and background-job behavior	Inspect the event type; IP address and user agent may be null
Compliance export is incomplete	Raw page coverage and retention window	Re-run a complete paginated export and document the collection boundary

Troubleshooting workflow

Reproduce with a direct request from the endpoint reference.
Confirm organization slug, caller role, and response pagination.
Compare the requested action with the event-types endpoint.
Remove filters, then reintroduce them one at a time.
Verify the source action is covered by the deployed release.
Preserve raw responses before client-side filtering or export transforms.

Original troubleshooting guidance

Troubleshooting: