EndUser Audit Logs

Overview

The EndUser Audit Logs API provides access to audit logs that record end user operations and security events within the tenant. Use this for compliance requirements and security investigations.

EndUser vs Admin

This API provides audit logs for end user operations (stored in DB_CORE). For Admin user operation audit logs (stored in DB_ADMIN), use the Admin Audit Log API.

Endpoint List

Method	Endpoint	Description
GET	/api/admin/audit-logs	List audit logs
GET	/api/admin/audit-logs/:id	Get audit log details
POST	/api/admin/audit-logs/export	Export audit logs

---

List Audit Logs

Retrieve a list of audit logs.

Endpoint

GET /api/admin/audit-logs

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 50, max: 100)
cursor	string	-	Pagination cursor
actor_id	string	-	User ID of the actor
target_id	string	-	Resource ID of the target
action	string	-	Action type
resource_type	string	-	Resource type
start_date	string	-	Start date (ISO 8601 format)
end_date	string	-	End date (ISO 8601 format)
ip_address	string	-	IP address
result	string	-	Result (success, failure)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/audit-logs?action=user.create&start_date=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "log_abc123",
      "timestamp": "2024-01-22T10:30:00Z",
      "actor": {
        "id": "usr_admin001",
        "email": "admin@example.com",
        "type": "user"
      },
      "action": "user.create",
      "resource_type": "user",
      "resource_id": "usr_new789",
      "result": "success",
      "ip_address": "203.0.113.1",
      "user_agent": "Mozilla/5.0...",
      "changes": {
        "email": "newuser@example.com",
        "name": "New User"
      }
    }
  ],
  "total": 1250,
  "cursor": "eyJpZCI6ImxvZ19hYmMxMjMifQ=="
}

---

Get Audit Log Details

Retrieve detailed information for a specified audit log.

Endpoint

GET /api/admin/audit-logs/:id

Path Parameters

Parameter	Type	Required	Description
id	string	✓	Audit log ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/audit-logs/log_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "log_abc123",
  "timestamp": "2024-01-22T10:30:00Z",
  "actor": {
    "id": "usr_admin001",
    "email": "admin@example.com",
    "name": "Administrator",
    "type": "user",
    "role": "tenant_admin"
  },
  "action": "user.create",
  "action_description": "Created a user",
  "resource_type": "user",
  "resource_id": "usr_new789",
  "result": "success",
  "ip_address": "203.0.113.1",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "location": {
    "country": "JP",
    "city": "Tokyo"
  },
  "request": {
    "method": "POST",
    "path": "/api/admin/users",
    "body": {
      "email": "newuser@example.com",
      "name": "New User"
    }
  },
  "changes": {
    "before": null,
    "after": {
      "id": "usr_new789",
      "email": "newuser@example.com",
      "name": "New User",
      "status": "active"
    }
  },
  "metadata": {
    "request_id": "req_xyz456",
    "session_id": "sess_def789"
  }
}

---

Export Audit Logs

Export audit logs in CSV or JSON format.

Endpoint

POST /api/admin/audit-logs/export

Request Body

Field	Type	Required	Description
format	string	✓	Export format (csv, json)
start_date	string	✓	Start date (ISO 8601 format)
end_date	string	✓	End date (ISO 8601 format)
filters	object	-	Filter conditions

Request Example

curl -X POST "https://{tenant-domain}/api/admin/audit-logs/export" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-01-31T23:59:59Z",
    "filters": {
      "action": "user.*"
    }
  }'

Response Example

{
  "job_id": "job_export_abc123",
  "status": "pending",
  "created_at": "2024-01-22T10:30:00Z"
}

Exports are executed as asynchronous jobs. Check job status via the Jobs Management API.

---

Action Types

User Actions

Action	Description
user.create	User created
user.update	User updated
user.delete	User deleted
user.suspend	User suspended
user.unsuspend	User unsuspended
user.lock	User locked
user.unlock	User unlocked
user.anonymize	User anonymized

Authentication Actions

Action	Description
auth.login	Login
auth.logout	Logout
auth.login_failed	Login failed
auth.mfa_enabled	MFA enabled
auth.mfa_disabled	MFA disabled
auth.password_changed	Password changed
auth.password_reset	Password reset

Client Actions

Action	Description
client.create	Client created
client.update	Client updated
client.delete	Client deleted
client.secret_rotated	Secret rotated

Session Actions

Action	Description
session.revoke	Session revoked
session.revoke_all	All sessions revoked

Role & Policy Actions

Action	Description
role.create	Role created
role.update	Role updated
role.delete	Role deleted
role.assign	Role assigned
role.unassign	Role unassigned
policy.create	Policy created
policy.update	Policy updated
policy.delete	Policy deleted

Settings Actions

Action	Description
settings.update	Settings updated
webhook.create	Webhook created
webhook.update	Webhook updated
webhook.delete	Webhook deleted

---

Audit Log Retention

Audit logs are retained based on tenant settings. The default retention period is 90 days. You can modify the retention period via the Settings Management API.

Compliance Requirements

Set the audit log retention period appropriately according to regulatory requirements. For long-term storage needs, we recommend setting up periodic exports.