Skip to content

Audit Platform API Overview

This document provides a high-level overview of the Audit Platform API surface for writing and querying audit events. It is written for architects and engineers integrating with the Audit Platform.

The Audit Platform provides comprehensive audit logging and compliance capabilities for multi-tenant SaaS applications. This is a conceptual overview—concrete OpenAPI/Swagger documentation lives in the Audit Platform product repository.

Note

This is a conceptual overview of the Audit Platform API. Concrete OpenAPI/Swagger documentation with exact endpoints, request/response schemas, and authentication details lives in the Audit Platform product repository.

API Surface at a Glance

The Audit Platform API provides endpoints for:

  • Writing Events - Submit audit events from microservices
  • Querying Events - Query and search audit events
  • Retention Management - Configure retention policies
  • Compliance - Compliance reporting and alerts
  • Webhooks - Webhook notifications for events

Authentication and Authorization

Authentication Methods

  • OAuth2/OIDC - Standard OAuth2 client credentials flow
  • API Keys - Service API keys for programmatic access
  • Managed Identity - Azure Managed Identity for Azure-hosted services

Authorization

  • Tenant Isolation - All operations are scoped to tenants
  • Role-Based Access - RBAC for audit query access
  • Compliance Roles - Special roles for compliance access

See: Identity Platform API Overview for authentication details.

Main Resource Groups

Resource Group Examples Notes
Events /events, /events/{id}, /events/query Write and query audit events
Retention /retention/policies, /retention/policies/{id} Retention policy management
Compliance /compliance/reports, /compliance/alerts Compliance reporting
Webhooks /webhooks, /webhooks/{id} Webhook configuration
Exports /exports, /exports/{id}/download Event export and download

Common Usage Patterns

Pattern 1: Write Audit Event from Microservice

Steps:

  1. Authenticate with service credentials
  2. Write audit event
  3. Receive event ID
  4. Optionally query event later

Example Flow: 

POST /api/v1/events
{
  "eventType": "user.action",
  "tenantId": "tenant-123",
  "userId": "user-456",
  "action": "user.updated",
  "resource": "user",
  "resourceId": "user-456",
  "metadata": {
    "field": "email",
    "oldValue": "old@example.com",
    "newValue": "new@example.com"
  }
}

Response: { "eventId": "event-789", "timestamp": "2026-01-01T10:30:00Z" }

Pattern 2: Query Logs for Tenant

Steps:

  1. Authenticate with query credentials
  2. Query events by tenant, user, time range
  3. Filter and paginate results
  4. Process results

Example Flow: 

GET /api/v1/events/query?tenantId=tenant-123&userId=user-456&startTime=2026-01-01&endTime=2026-01-15&page=1&pageSize=100

Response: {
  "events": [...],
  "totalCount": 150,
  "page": 1,
  "pageSize": 100
}

Pattern 3: Compliance Reporting

Steps:

  1. Authenticate with compliance credentials
  2. Generate compliance report
  3. Download report
  4. Schedule recurring reports

Example Flow: 

POST /api/v1/compliance/reports
{
  "reportType": "user-access",
  "tenantId": "tenant-123",
  "startDate": "2026-01-01",
  "endDate": "2026-01-15"
}

GET /api/v1/compliance/reports/{reportId}/download

Error Handling and Status Codes

Standard HTTP Status Codes

  • 200 OK - Successful request
  • 201 Created - Event created successfully
  • 400 Bad Request - Invalid request (e.g., missing required fields)
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error
  • 503 Service Unavailable - Service temporarily unavailable

Error Response Format

{
  "error": {
    "code": "INVALID_EVENT_TYPE",
    "message": "Event type 'invalid.type' is not allowed",
    "details": {
      "eventType": "invalid.type",
      "allowedTypes": ["user.action", "system.event", "compliance.event"]
    }
  }
}

Versioning and Compatibility

API Versioning

  • URL Versioning - /api/v1/, /api/v2/, etc.
  • Event Schema Versioning - Version event schemas for compatibility
  • Backward Compatibility - Maintain backward compatibility within major versions

Compatibility

  • Event Schema - JSON schema for events
  • Query API - Backward compatible query parameters
  • Webhooks - Versioned webhook payloads

Tip

Best Practices: 1. Use structured event formats 1. Include all required fields 1. Respect rate limits 1. Handle errors gracefully 1. Use webhooks for real-time notifications