Audit logs

Thalassa Cloud records an audit trail of API activity and security-sensitive operations in your organisation. Audit logs help you investigate changes, trace who did what, monitor authentication failures, and meet compliance requirements.

Audit logging is enabled by default for every organisation. Entries are read-only — they cannot be modified or deleted through the API. Logs are retained for a configurable period, then removed automatically.

Availability

Audit logs are a core platform feature and available for all services and platform API’s.

View logs in the console or via the tenant API at /v1/audit. Listing and reading audit logs requires the audit_log IAM permission (list / read).

What is logged

Platform API activity

Organisation-scoped API calls produce an audit entry. Each entry typically includes:

Field	Description
`eventID`	Unique identifier for the event
`createdAt`	Timestamp (UTC)
`action`	HTTP method (`GET`, `POST`, `PUT`, `DELETE`, …) or a service-specific action name
`resourceType`	API resource type (for example `cloud_vpc`, `kubernetes_cluster`, `dns_zone`)
`resourceIdentity`	Identity of the affected resource, when applicable
`description`	Human-readable summary when provided by the service
`user` / `serviceAccount` / `client`	The principal that performed the action
`impersonatorIdentity`	Support or admin impersonation, when applicable
`projectId`	Active project context, when set on service-specific entries
`context`	Request metadata (see below)

Request context (context object) for API activity:

Context key	Description
`client_ip`	Source IP address
`country_code`	ISO country derived from client IP (when available)
`user_agent`	Client user agent
`method`, `path`, `url`	HTTP request details
`status`	HTTP response status code
`duration`	Request processing time
`credentials_id`, `credentials_type`	Access credential used for the request, when applicable
`headers`	Safe request headers only (`User-Agent`, `Referer`, `X-Forwarded-For`, `Content-Type`, `Accept`, `X-Request-Id`, …)

Enhanced audit for sensitive services

Some services write additional dedicated entries with richer, security-focused context (alongside the generic HTTP audit entry):

KMS crypto operations

Action	Operation
`kms.encrypt`	Encrypt data
`kms.decrypt`	Decrypt data
`kms.sign` / `kms.verify`	Sign or verify data
`kms.hmac` / `kms.verify_hmac`	HMAC operations
`kms.rotate` / `kms.rotate.scheduled`	Manual or scheduled key rotation
`kms.export`	Export key material

resourceType: kms_key. Context includes region, key slug, key type, outcome, and sizes — never plaintext or ciphertext.

Filter with action=kms.encrypt,kms.decrypt,… or resourceType=kms_key.

See KMS audit logging for monitoring guidance and field details.

Secrets Manager

Action	Operation
`secrets.create`	Create a secret
`secrets.get_value`	Read secret payload
`secrets.put_value`	Write a new secret version
`secrets.update_policy`	Update access policy
`secrets.destroy_version`	Destroy a version
`secrets.delete`	Delete a secret

resourceType: secret. The resource identity is the canonical secret path (for example /app/production/db/password).

Metadata-only operations (list, browse, get secret metadata without revealing the value) produce only the generic HTTP audit entry.

Get-value and put-value operations also emit underlying kms.decrypt / kms.encrypt entries for the bound KMS key.

See Secrets Manager audit logging for field details and dual KMS correlation.

Authentication events

OAuth and token flows log dedicated entries for successful and failed client credential grants (oidc/client_credentials, oidc/client_credentials_failed), token exchanges, and related security events. These feed the failed-auth and security report endpoints.

Retention

Setting	Default	Description
`auditLogRetentionDays`	14 days	How long audit entries are kept per organisation

Expired entries are permanently deleted by a daily cleanup job (02:00 UTC). Retention is configured on organisation settings — contact your account team if you need a longer retention window.

Viewing audit logs

List and search

GET /v1/audit returns a paginated list, newest first.

Query parameter	Description
`page`	Page number (default `0`)
`limit`	Results per page (default `100`)
`searchText`	Search in `description` (case-insensitive)
`userIdentity`	Filter by user
`impersonatorIdentity`	Filter by impersonating user
`serviceAccount`	Filter by service account identity
`action`	Comma-separated actions (for example `POST,DELETE` or `kms.decrypt`)
`resourceType`	Comma-separated resource types (for example `cloud_vpc,dns_zone`)
`resourceIdentity`	Filter by specific resource identity
`includeSystemServices`	Include OIDC client / internal service entries (`true` / `false`)

Get by event ID

GET /v1/audit/{eventId} returns the full entry for a single event.

Example audit entry

{
  "eventID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "createdAt": "2026-06-08T14:32:01Z",
  "action": "POST",
  "resourceType": "cloud_vpc",
  "resourceIdentity": "vpc-abc123",
  "userIdentity": "user-xyz",
  "organizationIdentity": "acme-corp",
  "context": {
    "client_ip": "203.0.113.42",
    "country_code": "NL",
    "method": "POST",
    "path": "/v1/vpcs",
    "status": "201",
    "duration": "45ms",
    "user_agent": "Thalassa-CLI/1.2.0"
  }
}

For bulk export from the CLI, see Exporting audit logs.

Security analytics

Beyond raw log search, the audit API provides aggregated security views. All endpoints require audit_log → list permission.

Endpoint	Purpose
`GET /v1/audit/security-summary`	High-level metrics: unique users, unique IPs, failed auth count, total events, last activity
`GET /v1/audit/failed-auth`	Recent failed authentication attempts (HTTP 401/403), with client IP and user agent
`GET /v1/audit/user-activity`	Per-user analytics: last seen, total actions, unique IPs, resource types touched
`GET /v1/audit/client-ips`	Distinct client IP addresses seen in audit logs (with optional filters)

Pre-generated security reports

The platform generates security reports in the background every six hours (rolling 30-day window). Fetch the latest report by type:

GET /v1/audit/reports/{reportType}

List available reports: GET /v1/audit/reports

Report type	Contents
`summary`	Aggregated security overview
`user_activity`	User activity breakdown
`failed_auth`	Failed authentication analysis
`client_ips`	Client IP usage patterns
`api_trends`	Daily and hourly API usage trends
`peak_times`	Peak usage hours and days
`suspicious_activity`	Multiple failed logins, unusual IPs, rapid request patterns
`resource_activity`	Top resources, actions, and access patterns
`access_credentials`	Credential inventory, expiry, and unused credentials
`token_exchanges`	Federated token exchange success and failure rates
`federated_identities`	Federated identity usage and expiry
`rbac_permissions`	Role bindings, wildcard permissions, and permission usage

Reports are point-in-time snapshots. Use live audit log queries for real-time investigation.

Access control

IAM resource: audit_log

Policy name	Slug	Permissions	Typical use
(included in org admin)	`org-admin`	Full org access including audit logs	Organisation administrators
(included in org auditor)	`org-auditor`	`read`, `list` on audit logs	Read-only compliance and security review
(included in IAM read)	`iam-read-access`	`read`, `list` on audit logs	IAM team visibility
`admin:all`	`admin`	All permissions on all resources	Organisation owner

Action	Permission
List audit logs, security summaries, reports	`audit_log` → `list`
Get single audit log entry	`audit_log` → `read`

Bind via organisation roles or project IAM policies. See Default IAM policies for the full built-in catalogue.

Audit logs are organisation-scoped — project IAM policies do not isolate audit visibility per project today, though individual entries may include a projectId when the underlying operation was project-scoped.

Kubernetes cluster audit logs

Kubernetes clusters support a separate control plane audit log profile (none, basic, or advanced) configured on the cluster itself. This controls Kubernetes API server audit logging inside the cluster — it is independent of platform audit logs described on this page.

Configure auditLogProfile when creating or updating a cluster. Platform audit logs still record Thalassa API calls that manage clusters (create, update, delete, kubeconfig download, etc.).

Billing

Audit log storage and API access are included with the platform at no extra charge. You are not billed per audit event or per query.

Longer retention storage for audit logs than the default may be charged.

Limits and behaviour

Topic	Detail
Immutability	Audit entries cannot be updated or deleted via the API
Retention	Default 14 days; older entries are permanently purged
Pagination	Default 100 entries per page
Actor types	Users, service accounts, OIDC clients, and impersonated sessions
Geo enrichment	Country code added from client IP when geolocation lookup succeeds
Write path	Asynchronous batched writes — API responses are not blocked by audit persistence
API base path	`/v1/audit`

Common investigation workflows

Who deleted a resource? Filter by resourceIdentity and action=DELETE, or search resourceType for the resource kind.

Failed logins or credential abuse Use GET /v1/audit/failed-auth or the failed_auth security report.

KMS or secrets access Filter action prefix kms. or secrets., or resourceType kms_key / secret.

User activity review Use GET /v1/audit/user-activity?userIdentity=… or the user_activity report.

Compliance export Paginate GET /v1/audit with filters and export results from the console or your own integration. Plan exports within your retention window. See Exporting audit logs for CLI-based export.