This endpoint will return the list of trails created when updating resources that belong to or relates to the specified account. The endpoint supports ordering and pagination
Example response for a trail created when a user updates its first_name.
[
{
"account_id": "A1615205284020316ACCOUNT",
"created": 1615219684.0,
"id": 42231,
"item_model": "User",
"item_operation": "update",
"item_pk": "[email protected]",
"payload": {
"previous": {
"first_name": "Jhonny"
},
"updated": {
"first_name": "Jhon"
}
},
"rel_item1_model": null,
"rel_item1_pk": null,
"rel_item2_model": null,
"rel_item2_pk": null,
"request_id": "427cc5bf-aa08-45a6-bb7f-69afc6935fef",
"request_ip": "1.2.3.4,5.6.7.8",
"request_method": "PUT",
"request_path": "/users/[email protected]",
"request_qp": null,
"request_utc_time": 1615219684.2102,
"token": "TF4E1961BE08EF5F3B1B720A7",
"token_owner": "[email protected]"
}
]
- account_id - the account id of the context under which the change happened created - timestamp for when the trail was created
- id - id of the trail
- item_model - the Model of the modified entity
- item_pk - the ID of the modified entity
- payload - a dictionary describing the changes made on the entity
- rel_item1_model/rel_item2_model - the Models of the related entities in relation with the modified entity
- rel_item1_model/rel_item2_model - the IDs of the related entities in relation with the modified entity
- request_id - the uniq id of the request that caused the change to happen
- request_ip - a list of comma separated forwarded IPs for the request
- request_path - the url path of the request
- request_qp - a dict presenting all query params used in the request
- request_utc_time - the time the request reached our API
- token - the token ID used to authenticate the request
- token_owner - the owner of the token used for authenticating the request, can be a user email address, a device ID or None
Models
Each time an Account/Device/Zone/Policy/ResourceSet/ActionSet/User/Token is created/updated/saved/deleted, or when their relation with other objects change, a trail will be created to record the event.
Here is the complete list of internal models tracked via trails:
- Account
- ActionSet
- Device
- Group
- Policy
- ResourceSet
- Token
- User
- Zone
and their relational models that are tracked:
- Devices Policies
- Groups Policies
- Tokens Policies
- Users Policies
- Users Groups
Filtering
These trails are intended for tracking who changed an entity, and as their number can grow large, we have multiple ways to filter the trails returned by this endpoint, in order to narrow the number of the results to the relevant ones.
All next filters are expected part of the request query params (?filter1=value1&filter2=value2&...):
- utc_start - the minimum trail creation time, by default it is 1 hour ago
- utc_end - the maximum trail creation time
- model - the model of the entity modified, or the model of a related entity of the modified one. It has to be one of the models presented above.
- pk - the ID of the modified entity, or the model of a related entity of the modified entity
- owner - the owner of the token used to make the request that created the trail. Can be a user email or a device ID.
- token - the token ID used to make the request that created the trail
- operation - the operation made on the entity. Accepts one of: create/save/update/delete.
- ip - the ip of the request initiator
- path - the url path of the request (without query params).
- method - the http method used by the request. Accepts one of: GET/POST/PUT/DELETE.
Notes:
- utc_start and utc_end accepts either an utc timestamp or a string like: '-2h', '-15m', etc.
- When filtering by model, results will include trails for which the itemmodel, relitem1model or relitem2_model is the specified model.
- It is recommended to use as many filters at the same time as possible, in order to reduce the number of returned results.