Audit Logs

Ithbat IAM logs every significant event — authentication attempts, admin actions, permission changes, SCIM syncs, and API calls — to an immutable audit log. The audit log is your primary tool for security investigations, compliance audits, and incident response.

---

What gets logged

Every log entry captures who did what, to which resource, from where, and when.

Authentication events

Event type	Description
auth.login	Successful user authentication
auth.login_failed	Failed authentication attempt
auth.logout	User logout
auth.mfa_verified	MFA challenge successfully completed
auth.mfa_failed	Failed MFA challenge
auth.password_reset	Password reset completed
auth.email_verified	Email address verified
auth.session_revoked	Session explicitly revoked
auth.account_locked	Account locked after repeated failures
auth.saml_login	Authentication via SAML
auth.social_login	Authentication via social provider
auth.passwordless_login	Authentication via magic link or OTP

User lifecycle events

Event type	Description
user.created	User account created
user.updated	User profile updated
user.deleted	User account deleted
user.suspended	User suspended
user.reactivated	Suspended user reactivated
user.unlocked	Locked account manually unlocked
user.password_changed	User changed their own password
user.mfa_enabled	User enabled MFA
user.mfa_disabled	User disabled MFA

Role and permission events

Event type	Description
role.created	New role created
role.updated	Role permissions modified
role.deleted	Role deleted
role.assigned	Role assigned to a user
role.revoked	Role removed from a user

Invitation events

Event type	Description
invitation.created	Invitation sent
invitation.accepted	Invitation accepted and account set up
invitation.revoked	Invitation revoked
invitation.expired	Invitation expired without being accepted

Tenant and settings events

Event type	Description
tenant.created	New tenant registered
tenant.updated	Tenant settings updated
tenant.suspended	Tenant suspended
tenant.reactivated	Tenant reactivated
settings.updated	Tenant settings changed
saml.config_created	SAML connection configured
saml.config_updated	SAML connection updated
saml.config_deleted	SAML connection deleted
scim.token_created	SCIM token generated
scim.token_revoked	SCIM token revoked

Provisioning events

Event type	Description
scim.user_synced	User created or updated via SCIM
scim.user_deprovisioned	User deactivated via SCIM
scim.group_synced	Group created or updated via SCIM
directory.sync_started	Directory sync job started
directory.sync_completed	Directory sync job completed
directory.sync_failed	Directory sync job failed

API and system events

Event type	Description
api.key_created	API key created
api.key_revoked	API key revoked
webhook.created	Webhook endpoint created
webhook.deleted	Webhook endpoint deleted

---

Log entry format

Every log entry has the same structure:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "tenantId": "c2e3f4a5-6b7c-8d9e-0f1a-2b3c4d5e6f70",
  "eventType": "auth.login",
  "actorId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "actorEmail": "[email protected]",
  "actorType": "user",
  "targetId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "targetType": "user",
  "ipAddress": "41.208.100.5",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "location": "Riyadh, SA",
  "success": true,
  "metadata": {
    "authMethod": "password",
    "mfaUsed": true
  },
  "createdAt": "2026-02-24T10:00:00Z"
}

Field	Description
id	Unique log entry ID
tenantId	The tenant this event belongs to
eventType	The event type string
actorId	ID of the user or system that performed the action
actorEmail	Email of the actor at the time of the event
actorType	user, admin, system, or scim
targetId	ID of the resource the action was performed on
targetType	Resource type (user, role, tenant, etc.)
ipAddress	Client IP address
userAgent	Browser/client user agent string
location	Approximate geographic location from IP
success	Whether the action succeeded
metadata	Event-specific additional data
createdAt	Timestamp (UTC, ISO 8601)

---

Viewing audit logs in the admin console

1. Go to Audit Logs in the admin sidebar.
2. Use the filter bar to narrow results:
   • Event type: Select one or more event types.
   • User: Filter by actor email or user ID.
   • Date range: Select a start and end date.
   • IP address: Filter by source IP.
   • Status: Filter by success or failure.
3. Click any row to view the full log entry, including metadata.

---

Querying audit logs via API

List events

GET /api/v1/audit/events
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

Supports the following query parameters:

Parameter	Type	Description
eventType	string	Filter by event type, e.g. auth.login
actorId	UUID	Filter by actor user ID
actorEmail	string	Filter by actor email (partial match)
targetId	UUID	Filter by target resource ID
success	bool	true or false
from	ISO 8601	Start of date range
to	ISO 8601	End of date range
ipAddress	string	Filter by IP address
page	int	Page number (default: 1)
limit	int	Results per page (default: 50, max: 200)

Example — failed login attempts in the last 24 hours:

GET /api/v1/audit/events?eventType=auth.login_failed&success=false&from=2026-02-23T10:00:00Z
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

Get a single event

GET /api/v1/audit/events/{id}
Authorization: Bearer {token}

Login history

GET /api/v1/audit/logins
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

Audit statistics

GET /api/v1/audit/stats
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

Returns counts of events by type and by day for the last 30 days.

Activity for a specific user

GET /api/v1/audit/users/{userId}/activity
Authorization: Bearer {token}

Login history for a specific user

GET /api/v1/audit/users/{userId}/logins
Authorization: Bearer {token}

History for a specific resource

Retrieve all events that affected a given resource:

GET /api/v1/audit/resources/{type}/{id}/history
Authorization: Bearer {token}

Example — all events on a specific user account:

GET /api/v1/audit/resources/user/3fa85f64-.../history
Authorization: Bearer {token}

My own activity (self-service)

Users can view their own activity without admin permissions:

GET /api/v1/audit/me/activity
Authorization: Bearer {user_token}

GET /api/v1/audit/me/logins
Authorization: Bearer {user_token}

---

Filtering by event category

You can filter on partial event type prefixes to get all events in a category:

To get all...	Use eventType filter
Authentication events	auth.*
User lifecycle events	user.*
Role events	role.*
SAML events	saml.*
SCIM events	scim.*

---

Exporting audit data

Export events for offline analysis, archiving, or SIEM ingestion.

Via admin console

1. Go to Audit Logs.
2. Apply filters for the date range and event types you want.
3. Click Export → JSON or Export → CSV.

Via API

POST /api/v1/logs/export
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "format": "json",
  "from": "2026-01-01T00:00:00Z",
  "to": "2026-01-31T23:59:59Z",
  "eventTypes": ["auth.login", "auth.login_failed", "user.created", "user.deleted"]
}

Export is asynchronous. Poll the job endpoint for completion:

GET /api/v1/jobs/{jobId}/status
Authorization: Bearer {token}

---

Streaming logs

For real-time ingestion into a SIEM (Splunk, Datadog, Elastic), stream logs via:

1. Webhooks — subscribe to the event types you need. Ithbat POSTs each event to your endpoint in real time. See Webhooks.
2. Log streaming API — poll or stream:

GET /api/v1/logs/stream
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

---

Retention policy

Plan	Default retention	Maximum
Starter	30 days	30 days
Growth	90 days	90 days
Enterprise	1 year	Custom (up to 7 years)

Logs are immutable — they cannot be modified or deleted before their retention period expires.

---

Audit log API reference

Method	Endpoint	Permission
GET	/api/v1/audit/events	audit:read
GET	/api/v1/audit/events/{id}	audit:read
GET	/api/v1/audit/logins	audit:read
GET	/api/v1/audit/stats	audit:read
GET	/api/v1/audit/users/{userId}/activity	audit:read
GET	/api/v1/audit/users/{userId}/logins	audit:read
GET	/api/v1/audit/resources/{type}/{id}/history	audit:read
GET	/api/v1/audit/me/activity	Authenticated user
GET	/api/v1/audit/me/logins	Authenticated user
POST	/api/v1/logs/export	log:read
GET	/api/v1/logs/stream	log:read

---

Next steps

• Webhooks — stream audit events to your SIEM in real time
• RBAC & Permissions — control who has audit:read access
• User Management — investigate specific user events