Audit Log Endpoint Reference

Organization audit-log response models, event types, query parameters, and endpoint contracts.

AuthOS release 0.8.2 API v1 Latest-only documentation
Updated Jul 15, 2026 Edit this page
On this page

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.

User Management Events

Event Description Target Type
user.invited User invited to organization user
user.joined User accepted invitation user
user.removed User removed from organization user
user.role_updated User role changed (owner/admin/member) user

Service Management Events

Event Description Target Type
service.created New service created service
service.updated Service configuration updated service
service.deleted Service deleted service
service.oauth_credentials.updated OAuth credentials configured service

Organization Management Events

Event Description Target Type
organization.updated Organization details updated organization
organization.smtp.configured SMTP settings configured organization
organization.smtp.removed SMTP settings removed organization

Plan Management Events

Event Description Target Type
plan.created Subscription plan created plan
plan.updated Plan details updated plan
plan.deleted Plan deleted plan

Subscription Management Events

Event Description Target Type
subscription.created User subscribed to plan subscription
subscription.updated Subscription modified subscription
subscription.canceled Subscription canceled subscription

Invitation Management Events

Event Description Target Type
invitation.accepted Invitation accepted invitation
invitation.declined Invitation declined invitation
invitation.expired Invitation expired invitation
invitation.revoked Invitation revoked invitation

Security Events

Event Description Target Type
security.mfa.enabled MFA enabled user
security.mfa.disabled MFA disabled user
security.password.changed Password changed user

API Key Management Events

Event Description Target Type
api_key.created API key created api_key
api_key.deleted API key deleted api_key

Custom Domains & Branding Events

Event Description Target Type
domain.set Custom domain set organization
domain.verified Custom domain verified organization
domain.deleted Custom domain removed organization
branding.updated Branding settings updated organization

Endpoints Summary

Method Path Description Permissions
GET /api/organizations/:org_slug/audit-log Get audit logs Owner/Admin
GET /api/organizations/:org_slug/audit-log/event-types Get available event types Owner/Admin

Audit Log Operations

GET /api/organizations/:org_slug/audit-log

Retrieve paginated audit logs for an organization with optional filtering.

Permissions: Owner or Admin

Headers:

Header Value
Authorization Bearer {jwt}

Path Parameters:

Parameter Type Description
org_slug string Organization slug

Query Parameters:

Parameter Type Required Description
page integer No Page number (default: 1, min: 1)
limit integer No Items per page (default: 50, max: 100)
action string No Filter by specific action (e.g., service.created)
target_type string No Filter by target type (e.g., service, user)
target_id string No Filter by specific target ID (requires target_type)

Example Request (All Logs):

curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?page=1&limit=50" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Example Request (Filter by Action):

curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?action=service.created" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Example Request (Filter by Target):

curl -X GET "https://sso.example.com/api/organizations/acme-corp/audit-log?target_type=service&target_id=service-uuid" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Example Response (200 OK):

{
  "logs": [
    {
      "id": "log-uuid-1",
      "org_id": "org-uuid",
      "actor": {
        "id": "user-uuid",
        "email": "admin@acme.com",
        "is_platform_owner": false
      },
      "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,
      "details": {
        "service_slug": "main-app",
        "service_name": "Main Application",
        "service_type": "web",
        "client_id": "client-uuid"
      },
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "log-uuid-2",
      "org_id": "org-uuid",
      "actor": {
        "id": "user-uuid",
        "email": "admin@acme.com",
        "is_platform_owner": false
      },
      "action": "user.invited",
      "target_type": "user",
      "target_id": "invited-user-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,
      "details": {
        "invited_email": "newuser@acme.com",
        "role": "member"
      },
      "created_at": "2025-01-15T11:00:00Z"
    },
    {
      "id": "log-uuid-3",
      "org_id": "org-uuid",
      "actor": {
        "id": "user-uuid",
        "email": "admin@acme.com",
        "is_platform_owner": false
      },
      "action": "api_key.created",
      "target_type": "api_key",
      "target_id": "api-key-uuid",
      "ip_address": "203.0.113.42",
      "user_agent": "curl/7.79.1",
      "success": true,
      "details": {
        "api_key_id": "api-key-uuid",
        "service_id": "service-uuid",
        "service_slug": "main-app",
        "name": "Production Backend",
        "permissions": ["read:users", "read:subscriptions"],
        "expires_at": "2025-04-15T10:30:00Z"
      },
      "created_at": "2025-01-15T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

Error Responses:

  • 401 Unauthorized: Invalid or missing JWT
  • 403 Forbidden: User is not an owner or admin
  • 404 Not Found: Organization not found
  • 500 Internal Server Error: Database error

Notes:

  • Logs are returned in reverse chronological order (newest first)
  • Actor information is populated with user details
  • metadata field contains action-specific context (JSON)
  • success: false indicates failed actions (e.g., validation errors)
  • IP address and user agent may be null for background jobs
  • Maximum 100 items per page
  • Use action filter for specific event types
  • Use target_type + target_id to see all actions on a specific resource

Filtering Examples:

# All service-related events
GET /api/organizations/acme-corp/audit-log?target_type=service

# All actions by a specific user (as target)
GET /api/organizations/acme-corp/audit-log?target_type=user&target_id=user-uuid

# All failed actions
# (Note: filtering by success not currently supported - filter on client)

# Events from the last 7 days
# (Note: date filtering not currently supported - filter on client)

GET /api/organizations/:org_slug/audit-log/event-types

Get available audit event types for filtering.

Permissions: Owner or Admin

Headers:

Header Value
Authorization Bearer {jwt}

Path Parameters:

Parameter Type Description
org_slug string Organization slug

Example Request:

curl -X GET https://sso.example.com/api/organizations/acme-corp/audit-log/event-types \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Example Response (200 OK):

[
  {
    "value": "user.invited",
    "label": "User Invited",
    "category": "User Management"
  },
  {
    "value": "user.joined",
    "label": "User Joined",
    "category": "User Management"
  },
  {
    "value": "user.removed",
    "label": "User Removed",
    "category": "User Management"
  },
  {
    "value": "user.role_updated",
    "label": "User Role Updated",
    "category": "User Management"
  },
  {
    "value": "service.created",
    "label": "Service Created",
    "category": "Service Management"
  },
  {
    "value": "service.updated",
    "label": "Service Updated",
    "category": "Service Management"
  },
  {
    "value": "service.deleted",
    "label": "Service Deleted",
    "category": "Service Management"
  },
  {
    "value": "service.oauth_credentials.updated",
    "label": "Service OAuth Credentials Updated",
    "category": "Service Management"
  },
  {
    "value": "organization.updated",
    "label": "Organization Updated",
    "category": "Organization Management"
  },
  {
    "value": "organization.smtp.configured",
    "label": "Organization SMTP Configured",
    "category": "Organization Management"
  },
  {
    "value": "organization.smtp.removed",
    "label": "Organization SMTP Removed",
    "category": "Organization Management"
  },
  {
    "value": "plan.created",
    "label": "Plan Created",
    "category": "Plan Management"
  },
  {
    "value": "plan.updated",
    "label": "Plan Updated",
    "category": "Plan Management"
  },
  {
    "value": "plan.deleted",
    "label": "Plan Deleted",
    "category": "Plan Management"
  },
  {
    "value": "subscription.created",
    "label": "Subscription Created",
    "category": "Subscription Management"
  },
  {
    "value": "subscription.updated",
    "label": "Subscription Updated",
    "category": "Subscription Management"
  },
  {
    "value": "subscription.canceled",
    "label": "Subscription Canceled",
    "category": "Subscription Management"
  },
  {
    "value": "invitation.accepted",
    "label": "Invitation Accepted",
    "category": "Invitation Management"
  },
  {
    "value": "invitation.declined",
    "label": "Invitation Declined",
    "category": "Invitation Management"
  },
  {
    "value": "invitation.expired",
    "label": "Invitation Expired",
    "category": "Invitation Management"
  },
  {
    "value": "invitation.revoked",
    "label": "Invitation Revoked",
    "category": "Invitation Management"
  },
  {
    "value": "security.mfa.enabled",
    "label": "MFA Enabled",
    "category": "Security"
  },
  {
    "value": "security.mfa.disabled",
    "label": "MFA Disabled",
    "category": "Security"
  },
  {
    "value": "security.password.changed",
    "label": "Password Changed",
    "category": "Security"
  },
  {
    "value": "api_key.created",
    "label": "API Key Created",
    "category": "API Key Management"
  },
  {
    "value": "api_key.deleted",
    "label": "API Key Deleted",
    "category": "API Key Management"
  },
  {
    "value": "domain.set",
    "label": "Domain Set",
    "category": "Custom Domains & Branding"
  },
  {
    "value": "domain.verified",
    "label": "Domain Verified",
    "category": "Custom Domains & Branding"
  },
  {
    "value": "domain.deleted",
    "label": "Domain Deleted",
    "category": "Custom Domains & Branding"
  },
  {
    "value": "branding.updated",
    "label": "Branding Updated",
    "category": "Custom Domains & Branding"
  }
]

Error Responses:

  • 401 Unauthorized: Invalid or missing JWT
  • 403 Forbidden: User is not an owner or admin
  • 404 Not Found: Organization not found (path parameter only, no other 404s)
  • 500 Internal Server Error: Database error

Notes:

  • Returns all available event types with human-readable labels
  • Categorized for UI organization (e.g., dropdown groups)
  • Use value field for filtering in /audit-log endpoint
  • Event types are static and defined in the API code
  • New event types may be added in future versions