Authdog
Observability guide

Audit Logs

Authdog audit logs expose environment identity activity and organization-level administrative changes for investigation and operational monitoring. Use the console for interactive triage and the verified REST routes for controlled retrieval. Event context varies by source, so treat fields and payload details as nullable, discover event types from the environment, and avoid unsupported claims about retention, immutability, or compliance.

Prerequisites

  • Tenant, project, and environment identifiers for the system being investigated.
  • Console access to Audit.
  • For REST retrieval, a server-held Authdog API token with only the required scope.
  • A UTC incident window, known user or external ID, and expected event category where possible.
  • An approved evidence destination with encryption, access control, and its own retention policy.

Environment records can include event type and category, timestamp, tenant, application, environment, organization, provider, external ID, remote IP, user agent, user summary, location, and a source-specific JSON payload. Organization records can include actor, authentication method, resource type and ID, previous and new values, remote IP, user agent, and environment context.

Implementation

  1. Select the correct scope. In the console, choose the intended tenant, project, and environment before opening Audit. Record those identifiers with the incident. An empty result in one environment does not prove that no event occurred in another.

  2. Start with a narrow query. Choose a short UTC time range around the reported action. Filter using a known user, event type, external ID, location, browser, operating system, or event details. Expand the window only after confirming timestamps and timezone assumptions.

  3. Use the overview and event feed. The Audit module provides overview, events, and event-types views. Use overview to understand volume and categories, then move to the event feed for individual records. Saved filters can preserve recurring combinations of time, category, event type, location, browser, OS, user, and search criteria; name them by operational purpose rather than a specific incident.

  4. Discover types instead of guessing. The event-types explorer groups observed and catalog-backed types, reports counts, shows recent samples where available, and infers a prototype schema from up to 20 observed payload samples. A zero-count catalog entry has no observed activity. Use a real sample before building parsing or alerting rules.

  5. Retrieve environment records when automation is required. The repository verifies this public REST route with Bearer authentication:

    curl --get \
  "https://api.authdog.com/v1/tenants/$TENANT_ID/environments/$ENVIRONMENT_ID/audit/logs" \
  -H "Authorization: Bearer $AUTHDOG_API_TOKEN" \
  --data-urlencode "startDateTime=2026-07-01T00:00:00Z" \
  --data-urlencode "endDateTime=2026-07-02T00:00:00Z" \
  --data-urlencode "eventTypes=SIGNIN_SUCCESS,MFA_SIGNIN_FAILURE" \
  --data-urlencode "limit=100"

    The response contains logs, total, and optional meta. Pagination uses numeric offset and limit; limit must be between 1 and 500. Supported filters include time bounds, relative time, event type or comma-separated event types, category or categories, general and event-detail search, external ID, user IDs, browsers, operating systems, and locations.

  6. Inspect the catalog for the environment. Use GET /v1/tenants/{tenantId}/environments/{environmentId}/audit/event-types/catalog to retrieve event/category pairs. Metadata and grouped type routes are also available under the same audit path. Build filters from returned values rather than maintaining an exhaustive hard-coded list.

  7. Retrieve organization administration records separately. Use GET /v1/organizations/{organizationId}/audit/logs for organization-level records. It supports time, event type or category, search, resource type, numeric offset, and a maximum limit of 500. Keep environment identity activity and organization administration conceptually separate when constructing a timeline.

  8. Build the incident timeline. Identify the first relevant event, then record event ID, UTC timestamp, actor or user, remote IP, provider, user agent, and organization context when present. Correlate adjacent sign-in, MFA, membership, role, provisioning, and configuration activity. Preserve raw payloads before remediation, then confirm the remediation produces the expected state and follow-up activity.

Security considerations

Keep API tokens server-side and out of browser code, shell history shared with others, logs, and documentation. Audit payloads can contain personal and security-sensitive context. Restrict export access, encrypt files in transit and at rest, redact tickets, and delete temporary copies according to your policy.

Parse eventPayload defensively. It can be a source-specific serialized value and may add fields over time. Preserve unknown fields, tolerate missing context, and never make an authorization decision from audit data.

Authdog exposes recorded data, but this guide makes no fixed retention, immutable-storage, tamper-evidence, or compliance guarantee. If your organization requires a controlled long-term archive, export or forward verified events to a destination you govern and test retrieval independently.

Validation checklist

  • Query uses the intended tenant, environment, organization, and UTC range.
  • A known test sign-in or administrative action appears in the console.
  • Event type comes from the catalog or an observed record.
  • REST totals and pagination produce no unintended gaps or duplicate processing.
  • Parser tolerates null fields, unknown keys, and non-object payload values.
  • Saved filter reproduces the intended event set.
  • Export destination restricts access and applies your retention policy.
  • Remediation state is verified directly, not inferred only from an audit event.

Troubleshooting

For no results, verify environment and timezone first, then remove filters one at a time. Catalog entries with zero counts are valid but have no observed sample. If a sample schema differs from another record, treat the inferred schema as a convenience, not a contract.

For pagination gaps, keep filters and sort assumptions stable while changing numeric offset. Do not exceed the 500-record limit. If API access fails while console access works, confirm token scope and that the token is being sent only to https://api.authdog.com/v1.

If organization changes are missing from the environment feed, query the organization audit route. If identity activity lacks organization context, correlate by user, timestamp, external ID, and adjacent membership records without assuming a nullable field exists.

Next steps