Audit Logs API

Auris automatically records every administrative action, authentication event, and security-relevant operation in an immutable audit trail. The Audit Logs API provides read access to these logs and management of log streaming configurations that forward events to external observability platforms.

Audit logs are retained according to your plan’s retention policy. All log entries are immutable — they cannot be edited or deleted through the API.

All endpoints require the x-tenant header and a valid Bearer token.

Querying Logs

GET/api/logs/auditRequires: view:audit

List audit log entries with filtering and pagination. Results are returned in reverse chronological order (newest first). Supports filtering by action, user, resource type, severity level, date range, and free-text search.

Query parameters

Parameter	Type	Description
`offset`	integer	Number of records to skip (default: 0)
`limit`	integer	Items per page (default: 50, max: 500)
`action`	string	Filter by action name (e.g., `user.login`, `role.update`, `sso.connection.create`)
`userId`	string	Filter by the user ID who performed the action
`startDate`	ISO 8601	Start of date range (inclusive)
`endDate`	ISO 8601	End of date range (inclusive)
`excludeActions`	string	Comma-separated list of action names to exclude. Defaults to `PERMISSION_CHECK`.

Example request


GET /api/logs/audit?action=LOGIN&startDate=2025-02-01T00:00:00Z&limit=50

Success response


{
  "data": [
    {
      "id": "log_abc123",
      "action": "LOGIN",
      "userId": "usr_def456",
      "resource": "session",
      "resourceId": "sess_ghi789",
      "status": "failure",
      "errorCode": "invalid_credentials",
      "errorMessage": "Invalid credentials",
      "metadata": {
        "method": "password"
      },
      "clientIp": "203.0.113.42",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "createdAt": "2025-02-18T14:30:00Z"
    },
    {
      "id": "log_jkl012",
      "action": "ROLE_UPDATED",
      "userId": "usr_admin001",
      "resource": "role",
      "resourceId": "role_mno345",
      "status": "success",
      "errorCode": null,
      "errorMessage": null,
      "metadata": {
        "permissions": ["view:invoices", "create:invoices", "edit:invoices"]
      },
      "clientIp": "10.0.1.50",
      "userAgent": "AurisConsole/1.0",
      "createdAt": "2025-02-18T13:15:00Z"
    }
  ],
  "pagination": {
    "total": 1284,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Log Entry Shape

Every audit log entry has the following structure:

Field	Type	Description
`id`	string	Unique identifier for the log entry
`action`	string	The action that was performed, in `UPPER_SNAKE_CASE` (e.g., `LOGIN`, `USER_CREATED`, `ROLE_ASSIGNMENT`)
`userId`	string \| null	The user who performed the action. Null for system-generated events (cron jobs, webhooks).
`resource`	string \| null	The type of resource affected (e.g., `user`, `session`, `2fa_settings`)
`resourceId`	string \| null	The ID of the specific resource affected
`status`	`success` \| `failure` \| `pending`	Outcome of the action. There is no severity level.
`errorMessage`	string \| null	Failure detail, present when `status` is `failure`
`errorCode`	string \| null	Machine-readable failure code, present when `status` is `failure`
`metadata`	object \| null	Action-specific data
`clientIp`	string \| null	IP address of the client that triggered the action
`userAgent`	string \| null	User-Agent header from the request
`createdAt`	ISO 8601	Timestamp of when the event occurred

action values are not dot-notation. Dot-notation strings such as user.login are event-subscription event types — a separate namespace used by webhooks. Filtering audit logs with ?action=user.login matches nothing; use ?action=LOGIN.

Common Action Types

These are the values stored in action. The right-hand column is the corresponding webhook event type, for cross-referencing with event subscriptions — it is not a value you can filter on here.

`action` (stored)	Webhook event type	Description
`LOGIN`	`user.login`	User login attempt (`status` distinguishes success from failure)
`LOGOUT`	`user.logout`	User signed out
`SIGNUP`	`user.created`	New user registration
`USER_CREATED`	`user.created`	Admin created a user
`USER_UPDATED`	`user.updated`	User profile updated
`USER_DELETED`	`user.deleted`	User account deleted
`PASSWORD_CHANGE`	`user.password_changed`	Password changed
`PASSWORD_RESET`	`user.password_changed`	Password reset initiated
`ROLE_CREATED`	`role.created`	Role created
`ROLE_UPDATED`	`role.updated`	Role metadata updated
`ROLE_DELETED`	`role.deleted`	Role deleted
`ROLE_ASSIGNMENT`	`role.assigned`	Role assigned to a user
`ROLE_REMOVAL`	`role.removed`	Role removed from a user
`PERMISSION_SYNC`	`permission.changed`	Role permissions changed
`PERMISSION_CHECK`	—	Permission evaluation. High volume: excluded by default, see `excludeActions`.

The details field for mutation events (create, update, delete) typically includes before and after snapshots where applicable. For sensitive fields like passwords and secrets, only the fact that the field changed is recorded — not the actual values.

Log Streaming

Log streaming forwards audit events in real-time to external observability and SIEM platforms. When a log stream is configured and active, every audit event is sent to the configured destination in addition to being stored in the Auris database.

GET/api/log-streamsRequires: admin:all

List all configured log streams for the tenant. Returns stream metadata, type, status, and last delivery time.

Success response


{
  "success": true,
  "data": [
    {
      "id": "ls_abc123",
      "name": "Production Datadog",
      "type": "DATADOG",
      "status": "active",
      "config": {
        "region": "us1",
        "apiKey": "dd_api_***...***"
      },
      "lastDeliveryAt": "2025-02-18T14:29:55Z",
      "createdAt": "2025-01-10T09:00:00Z"
    },
    {
      "id": "ls_def456",
      "name": "SIEM Webhook",
      "type": "WEBHOOK",
      "status": "active",
      "config": {
        "url": "https://siem.internal.acme.com/auris-logs",
        "headers": { "X-Custom-Header": "value" }
      },
      "lastDeliveryAt": "2025-02-18T14:29:58Z",
      "createdAt": "2025-02-01T11:30:00Z"
    }
  ]
}

POST/api/log-streamsRequires: admin:all

Create a new log stream. Each stream type requires a different configuration shape. Auris validates the configuration and optionally performs a test delivery before saving.

Stream Type: WEBHOOK

Sends each audit event as an HTTP POST to the specified URL. Supports custom headers for authentication.

Request body


{
  "name": "SIEM Webhook",
  "type": "WEBHOOK",
  "config": {
    "url": "https://siem.internal.acme.com/auris-logs",
    "headers": {
      "Authorization": "Bearer your-siem-token",
      "X-Source": "auris"
    }
  }
}

Config Field	Required	Description
`url`	Yes	HTTPS endpoint to receive log events
`headers`	No	Custom HTTP headers sent with each delivery

The webhook payload is the JSON audit log entry, sent with Content-Type: application/json.

Stream Type: AMAZON_S3

Batches audit events and uploads them as JSON files to an S3-compatible bucket.

Request body


{
  "name": "S3 Archive",
  "type": "AMAZON_S3",
  "config": {
    "bucket": "auris-audit-logs",
    "region": "us-east-1",
    "accessKeyId": "<your-aws-access-key-id>",
    "secretAccessKey": "<your-aws-secret-access-key>",
    "prefix": "auris/tenant-name/"
  }
}

Config Field	Required	Description
`bucket`	Yes	S3 bucket name
`region`	Yes	AWS region (e.g., `us-east-1`)
`accessKeyId`	Yes	AWS access key ID with `s3:PutObject` permission
`secretAccessKey`	Yes	AWS secret access key
`prefix`	No	Key prefix for uploaded files (default: `auris-logs/`)

Files are uploaded with keys in the format: {prefix}YYYY/MM/DD/HH-mm-ss-{uuid}.json.

Stream Type: DATADOG

Datadog is a US-hosted third-party SaaS service. Depending on your data-residency and compliance requirements, verify that forwarding audit events to Datadog is permitted under your policies before enabling this stream type.

Sends audit events to the Datadog Log Management API.

Request body


{
  "name": "Datadog Logs",
  "type": "DATADOG",
  "config": {
    "apiKey": "dd_api_key_here",
    "region": "us1",
    "service": "auris-iam",
    "source": "auris"
  }
}

Config Field	Required	Description
`apiKey`	Yes	Datadog API key
`region`	Yes	Datadog region: `us1`, `us3`, `us5`, `eu1`, `ap1`
`service`	No	Service name tag (default: `auris`)
`source`	No	Source tag (default: `auris`)

Stream Type: SPLUNK

Sends audit events to Splunk via the HTTP Event Collector (HEC).

Request body


{
  "name": "Splunk HEC",
  "type": "SPLUNK",
  "config": {
    "hecUrl": "https://splunk.internal.acme.com:8088/services/collector/event",
    "hecToken": "your-hec-token",
    "index": "auris_audit",
    "source": "auris-iam",
    "sourcetype": "_json"
  }
}

Config Field	Required	Description
`hecUrl`	Yes	Splunk HEC endpoint URL
`hecToken`	Yes	HEC authentication token
`index`	No	Splunk index (default: `main`)
`source`	No	Source value (default: `auris`)
`sourcetype`	No	Sourcetype value (default: `_json`)

Optional body field: eventFilters

All stream types accept an optional eventFilters field to restrict which action types are forwarded to the destination.


{
  "name": "SIEM Webhook",
  "type": "WEBHOOK",
  "config": { "url": "https://siem.internal.acme.com/auris-logs" },
  "eventFilters": ["user.login", "role.update", "security.brute_force.lockout"]
}

Field	Type	Description
`eventFilters`	string[]	Optional array of action names to forward. When omitted, all actions are streamed.

Success response (all types)


{
  "success": true,
  "data": {
    "id": "ls_ghi789",
    "name": "Datadog Logs",
    "type": "DATADOG",
    "status": "active",
    "config": {
      "region": "us1",
      "apiKey": "dd_api_***...***",
      "service": "auris-iam",
      "source": "auris"
    },
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Sensitive fields in the config (API keys, secrets, tokens) are masked in GET responses. The full values are only used internally for delivery and are never exposed through the API after creation.

Error codes

Code	HTTP	Description
`VALIDATION_ERROR`	400	Missing required config fields or invalid stream type
`STREAM_NAME_TAKEN`	409	A log stream with this name already exists
`TEST_DELIVERY_FAILED`	400	Test delivery to the configured endpoint failed (returned when the endpoint is unreachable or rejects the test event)

GET/api/log-streams/[id]Requires: admin:all

Get full details for a specific log stream, including its configuration (with secrets masked), status, and delivery statistics.

Success response


{
  "success": true,
  "data": {
    "id": "ls_abc123",
    "name": "Production Datadog",
    "type": "DATADOG",
    "status": "active",
    "config": {
      "region": "us1",
      "apiKey": "dd_api_***...***",
      "service": "auris-iam",
      "source": "auris"
    },
    "lastDeliveryAt": "2025-02-18T14:29:55Z",
    "deliveryCount": 15420,
    "errorCount": 3,
    "lastError": null,
    "createdAt": "2025-01-10T09:00:00Z",
    "updatedAt": "2025-02-15T08:00:00Z"
  }
}

PATCH/api/log-streams/[id]Requires: admin:all

Update a log stream’s name, configuration, or status. Use this to rotate API keys, change endpoints, or pause/resume streaming.

Request body — update config


{
  "name": "Production Datadog (v2)",
  "config": {
    "apiKey": "new_dd_api_key_here"
  }
}

Request body — pause streaming


{
  "status": "paused"
}

Success response


{
  "success": true,
  "data": {
    "id": "ls_abc123",
    "name": "Production Datadog (v2)",
    "status": "active",
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Stream statuses:

Status	Description
`active`	Streaming events to the destination
`paused`	Stream is paused — events are not delivered but are still recorded in Auris
`error`	Delivery has failed repeatedly — stream is auto-paused until configuration is corrected

DELETE/api/log-streams/[id]Requires: admin:all

Delete a log stream. Delivery stops immediately. Historical audit logs are not affected — they remain in the Auris database regardless of streaming configuration.

Success response


{
  "success": true
}

Permissions Reference

Permission	Description
`view:audit`	Query and read audit log entries
`admin:all`	Create, update, delete, and configure log streaming destinations

Audit logs are append-only and immutable. There is no API endpoint to delete or modify log entries. This ensures the integrity of the audit trail for compliance purposes (SOC 2, ISO 27001, GDPR Article 30).

Webhook Delivery Format

For WEBHOOK-type log streams, each event is delivered as an HTTP POST with the following structure:

The event object is posted flat — there is no event, tenant or data wrapper:


{
  "action": "LOGIN",
  "resource": "session",
  "resourceId": "sess_ghi789",
  "status": "success",
  "userId": "usr_def456",
  "clientIp": "203.0.113.42",
  "userAgent": "Mozilla/5.0...",
  "metadata": { "method": "password" },
  "timestamp": "2025-02-18T14:30:00Z"
}

The webhook includes the headers configured in the log stream plus Content-Type: application/json and User-Agent: Auris-LogStream/1.0.

Deliveries are retried up to 8 attempts with exponential backoff and full jitter (roughly 30s, 60s, 120s, …, capped at 6 hours) on non-2xx responses. A stream is disabled automatically after 10 consecutive failures.

Log Streaming — Stream audit logs to external services like Datadog and Splunk
Logs & Compliance — View and filter logs from the Console

Audit Logs API

Querying Logs

Log Entry Shape

Common Action Types

Log Streaming

Stream Type: WEBHOOK

Stream Type: AMAZON_S3

Stream Type: DATADOG

Stream Type: SPLUNK

Optional body field: eventFilters

Success response (all types)

Permissions Reference

Webhook Delivery Format

Related