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.
count	The number of total audit logs belonging to the account.

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.
`current_state`	object / null	How the resource can be described as of right now (JSON).
`previous_state`	object / null	How the resource could be described before the event behind this audit log happened (JSON).

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,
            "current_state": null,
            "previous_state": 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",
            "current_state": null,
            "previous_state": {
                "created": "2024-03-12T15:05:40Z",
                "encrypted": false,
                "labels": [],
                "metadata": {
                    "backup_type": "automatic",
                    "os_storage": "00000000-0000-0000-0000-000000000000"
                },
                "origin": "00000000-0000-0000-0000-000000000000",
                "size": 25,
                "state": "maintenance",
                "title": "Simple backup of My simple server Device 1",
                "type": "backup",
                "uuid": "00000000-0000-0000-0000-000000000000",
                "zone": "fi-hel2"
            }
        }
    ],
    "count": 500
}

Notes:

The count is the total count of audit logs under the account, not the specific ones returned by the response.

Export audit logs

Returns every single audit log row for an account as either JSON or CSV response until the maximum audit log retention period (90 days).

Request

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

Request attributes (query parameters)

Attribute	Accepted value	Default value	Required	Description
format	"json" "csv"	"csv"	no	The format in which to receive the audit log list.

Audit Log object attributes

Attribute	Description
`time`	Time at which the audit log was recorded.
`auth_type`	Authentication method used for the event which created this audit log.
`upcloud_correlation_id`	Unique ID given to the event. Can occur multiple times for separate audit log events.
`resource_type`	Type of resource e.g. "account", "server", etc.
`action`	What was performed on the resource in question.
`origin`	Origin of the event such as "gui", "web" or "upcloud_internal".
`account_username`	Username of the account or subaccount performing the event.
`ip_address`	Source IP address of the event, if one could be determined.
`resource_id`	The ID of the resource that the audit log relates to.
`current_state`	How the resource can be described as of right now (JSON).
`previous_state`	How the resource could be described before the event behind this audit log happened (JSON).

Notes:

The attributes resource_type, action, and origin are only able to have one of a set list of values, described below by the endpoint /filter-options.

Normal response

HTTP/1.1 200 OK

As CSV:

Time,Auth Type,UpCloud Correlation ID,Resource Type,Action,Origin,Username,Authentication Type,IP Address,Current State,Previous State
2024-04-02 11:08:06.021896 +0000 UTC,gui,01HTFAEGT48JP7M5YFHC7W21MG,auth,login,gui,mrmagoo,gui,1.2.3.4,null,null
2024-03-13 17:50:26.647075 +0000 UTC,daemon,,storage,delete,upcloud_internal,mrmagoo,daemon,,null,"{""created"":""2024-03-12T15:05:40Z"",""encrypted"":false,""labels"":[],""metadata"":{""backup_type"":""automatic"",""os_storage"":""00000000-0000-0000-0000-000000000000""},""origin"":""00000000-0000-0000-0000-000000000000"",""size"":25,""state"":""maintenance"",""title"":""My simple backup Device 1"",""type"":""backup"",""uuid"":""00000000-0000-0000-0000-000000000000"",""zone"":""fi-hel2""}"
2024-03-13 17:50:11.11833 +0000 UTC,daemon,01HRWEZ6CHD54M3YVZH8E29WXJ,storage,update,upcloud_internal,mrmagoo,daemon,,"{""backup_rule"":{""interval"":""daily"",""retention"":""1"",""time"":""1500""},""backups"":[{""uuid"":""00000000-0000-0000-0000-000000000000""},{""uuid"":""00000000-0000-0000-0000-000000000000""}],""created"":""2023-10-07T18:18:49Z"",""encrypted"":false,""labels"":[],""size"":25,""state"":""online"",""tier"":""maxiops"",""title"":""My simple server Device 1"",""type"":""normal"",""uuid"":""00000000-0000-0000-0000-000000000000"",""zone"":""fi-hel2""}","{""backup_rule"":{""interval"":""daily"",""retention"":""1"",""time"":""1500""},""backups"":[{""uuid"":""00000000-0000-0000-0000-000000000000""}],""created"":""2023-10-07T18:18:49Z"",""encrypted"":false,""labels"":[],""size"":25,""state"":""online"",""tier"":""maxiops"",""title"":""My simple server Device 1"",""type"":""normal"",""uuid"":""00000000-0000-0000-0000-000000000000"",""zone"":""fi-hel2""}"
2024-03-13 17:50:11.104017 +0000 UTC,daemon,01HRWEZ6CHD54M3YVZH8E29WXJ,storage,create,upcloud_internal,mrmagoo,daemon,,"{""backups"":[],""created"":""2024-03-13T17:50:10Z"",""encrypted"":false,""labels"":[],""origin"":""00000000-0000-0000-0000-000000000000"",""size"":25,""state"":""online"",""title"":""Simple backup of My simple server Device 1"",""type"":""backup"",""uuid"":""00000000-0000-0000-0000-000000000000"",""zone"":""fi-hel2""}",null

As JSON:

[
    {
        "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,
        "current_state": null,
        "previous_state": 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",
        "current_state": null,
        "previous_state": {
            "created": "2024-03-12T15:05:40Z",
            "encrypted": false,
            "labels": [],
            "metadata": {
                "backup_type": "automatic",
                "os_storage": "00000000-0000-0000-0000-000000000000"
            },
            "origin": "00000000-0000-0000-0000-000000000000",
            "size": 25,
            "state": "maintenance",
            "title": "Simple backup of My simple server Device 1",
            "type": "backup",
            "uuid": "00000000-0000-0000-0000-000000000000",
            "zone": "fi-hel2"
        }
    },
    {
        "time": "2024-03-13T17:50:11.11833Z",
        "auth_type": "daemon",
        "upcloud_correlation_id": "01HRWEZ6CHD54M3YVZH8E29WXJ",
        "resource_type": "storage",
        "action": "update",
        "origin": "upcloud_internal",
        "account_username": "mrmagoo",
        "ip_address": "",
        "resource_id": "00000000-0000-0000-0000-000000000000",
        "current_state": {
            "backup_rule": {
                "interval": "daily",
                "retention": "1",
                "time": "1500"
            },
            "backups": [
                {
                "uuid": "00000000-0000-0000-0000-000000000000"
                },
                {
                "uuid": "00000000-0000-0000-0000-000000000000"
                }
            ],
            "created": "2023-10-07T18:18:49Z",
            "encrypted": false,
            "labels": [],
            "size": 25,
            "state": "online",
            "tier": "maxiops",
            "title": "My simple server Device 1",
            "type": "normal",
            "uuid": "00000000-0000-0000-0000-000000000000",
            "zone": "fi-hel2"
        },
        "previous_state": {
            "backup_rule": {
                "interval": "daily",
                "retention": "1",
                "time": "1500"
            },
            "backups": [
                {
                "uuid": "00000000-0000-0000-0000-000000000000"
                }
            ],
            "created": "2023-10-07T18:18:49Z",
            "encrypted": false,
            "labels": [],
            "size": 25,
            "state": "online",
            "tier": "maxiops",
            "title": "My simple server Device 1",
            "type": "normal",
            "uuid": "00000000-0000-0000-0000-000000000000",
            "zone": "fi-hel2"
        }
    },
    {
        "time": "2024-03-13T17:50:11.104017Z",
        "auth_type": "daemon",
        "upcloud_correlation_id": "01HRWEZ6CHD54M3YVZH8E29WXJ",
        "resource_type": "storage",
        "action": "create",
        "origin": "upcloud_internal",
        "account_username": "mrmagoo",
        "ip_address": "",
        "resource_id": "00000000-0000-0000-0000-000000000000",
        "current_state": {
            "backups": [],
            "created": "2024-03-13T17:50:10Z",
            "encrypted": false,
            "labels": [],
            "origin": "00000000-0000-0000-0000-000000000000",
            "size": 25,
            "state": "online",
            "title": "Simple backup of My simple server Device 1",
            "type": "backup",
            "uuid": "00000000-0000-0000-0000-000000000000",
            "zone": "fi-hel2"
        },
        "previous_state": null
    }
]

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"]
}