Skip to content

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 180 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.

Pagination

Upcloud-Total-Count header is included in the response to indicate the total number of audit logs available with the current query parameters (excluding limit and offset). The total count can be used for a number of pagination strategies. limit and offset query parameters can be used to finally paginate the results.

Request

GET /1.3/audit-logs HTTP/1.1

Request attributes (query parameters)

Attribute Accepted values 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-01-01T23:45:56Z 180 days ago 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"]
}

Export audit logs

Exports audit logs as a CSV or JSON file. The export is limited to 180 days. The export is synchronous and will stream the data to the client.

Example commands

The following command will export the audit logs as a CSV file on a MacOS/Unix-based system using curl. Replace <username> and <password> with your UpCloud credentials:

curl -u <username>:<password> "https://api.upcloud.com/1.3/audit-logs/export?format=csv" > audit-logs-export.csv

You can also use wget to download the file:

wget --auth-no-challenge --user=<username> --password=<password> "https://api.upcloud.com/1.3/audit-logs/export?format=csv" -O audit-logs-export.csv

On Windows, you can use PowerShell's Invoke-WebRequest. This requires PowerShell v6.0.0 or newer:

Invoke-WebRequest -Uri "https://api.upcloud.com/1.3/audit-logs/export?format=csv" -OutFile audit-logs-export.csv -Authentication Basic -Credential (Get-Credential)

Request

GET /1.3/audit-logs/export HTTP/1.1

Request attributes (query parameters)

Attribute Accepted values Default value Required Description
format csv / json csv no Export format.

Normal response

HTTP/1.1 200 OK

The response will contain the exported data in the requested format.