22. Audit Logs

The UpCloud Audit Logs provide a security-relevant, chronological record of events of an account and all its resources. This service holds data for up to 90 days per account. Included events:

• Account-related events
• Successful Hub logins events
• Server events
• Storage events
• Managed Database events
• Managed Load Balancer events
• Manage Object Storage events
• UpCloud Kubernetes Service events

List audit logs

Returns a list of audit log rows according to the query parameters. Note that this endpoint is paginated by default and the list is limited in results. See query parameters below.

Request

GET /1.3/audit-logs HTTP/1.1

Request attributes (query parameters)

Attribute	Accepted value	Default value	Required	Description
limit	0-200	50	no	Number of entries to receive at most.
offset	>= 0	0	no	Offset for retrieved results.
actions	create / read / update / delete / access-update / attach / detach / login / logout		no	List of actions to filter by.
origins	api / gui / upcloud_internal		no	List of origins to filter by.
resource_types	account / auth / init-script / managed-database / managed-loadbalancer / managed-loadbalancer-certificate-bundle / managed-object-storage / server / ssh-key / storage / uks		no	List of resource types to filter by.
created_after	ISO timestamp eg. 2024-04-05T15:04:05Z	Current time - 90 days	no	List audit logs created after the given timestamp (including the time of timestamp).
created_before	ISO timestamp eg. 2024-04-05T15:04:05Z	Current time	no	List audit logs created before the given timestamp (including the time of timestamp).
q	valid UUID, username or IP address (00798b85-efdc-41ca-8021-f6ef457b8531 / my_account / 0.0.0.0)		no	Filter audit logs using a keyword such as account username, resource ID or IP address.

Notes:

• The attributes resource_type, action, and origin can only be from a specific list of values, which can be found below in the /filter-options endpoint.

Response attributes

Attribute	Description
audit_logs	The list of audit log objects.

Audit Log object attributes

Attribute	Value	Description
time	string (ISO format)	Time at which the audit log was recorded.
auth_type	basic_auth / gui / daemon / null	Authentication method used for the event which created this audit log. null for internal events.
upcloud_correlation_id	string	Unique ID given to the event. Can occur multiple times for separate audit log events.
resource_type	string (see /filter-options)	Type of resource e.g. "account", "server", etc.
action	string / null (see /filter-options)	What was performed on the resource in question.
origin	api / gui / upcloud_internal	Origin of the interface where the event was triggered such as "gui", "api" or "upcloud_internal".
account_username	string / null	Username of the account or subaccount performing the event.
ip_address	string / null	Source IP address of the event, if one could be determined.
resource_id	string / null	The UUID of the resource that the audit log relates to.

Notes:

• The attributes resource_type and action can only be from a specific list of values, which can be found below in the /filter-options endpoint.

Normal response

HTTP/1.1 200 OK

{
  "audit_logs": [
    {
      "time": "2024-04-02T11:52:25.719619Z",
      "auth_type": "gui",
      "upcloud_correlation_id": "01HTFAEGT48JP7M5YFHC7W21MG",
      "resource_type": "auth",
      "action": "login",
      "origin": "gui",
      "account_username": "mrmagoo",
      "ip_address": "1.2.3.4",
      "resource_id": null
    },
    {
      "time": "2024-03-13T17:50:26.647075Z",
      "auth_type": "daemon",
      "upcloud_correlation_id": "",
      "resource_type": "storage",
      "action": "delete",
      "origin": "upcloud_internal",
      "account_username": "mrmagoo",
      "ip_address": "",
      "resource_id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

List options to filter by

Returns an object of available fields and options by which one can filter the audit logs response.

Request

GET /1.3/audit-logs/filter-options HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "resource_types": [
    "account",
    "auth",
    "init-script",
    "managed-database",
    "managed-loadbalancer",
    "managed-loadbalancer-certificate-bundle",
    "managed-object-storage",
    "server",
    "ssh-key",
    "storage",
    "uks"
  ],
  "actions": [
    "create",
    "read",
    "update",
    "delete",
    "access-update",
    "attach",
    "detach",
    "login",
    "logout"
  ],
  "origins": ["api", "gui", "upcloud_internal"]
}