Audit log
The audit log is a chronological set of records that document activities affecting Teamwire entities such as users and groups and other possibly security-relevant events such as administrator logins.
Manage audit log entries
Return a list of audit log entries
GET /v<api_version>/admin/audit_log/
If the call to this endpoint is done by a Superadmin, audit log entries for all organisations will be returned. Ordinary admins will only see audit log entries of their own organisation.
Every call to this endpoint will also generate an audit log entry for the viewing event itself.
Access restrictions
- Admins and Superadmins must have the allowViewAuditlog permission.
- Admins will receive a list of audit log entries in their own organisation only.
- Superadmins will receive a list of audit log entries in all organisations.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
GET parameters
The following parameters are specified as part of the query string
in the URL, i.e. ?param1=value2¶m2=value2:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
from_date |
String | Yes | All admins | If specified only audit log entries that occured on this date and time or later will be returned. A combined date/time in JavaScript’s standard ISO 8601-conforming format and with UTC as time zone is expected, i.e. “DDDD-MM-YYYY’T’HH:MM:SS.SSS’Z’“, for example “2019-03-19T13:41:11.257Z”. |
to_date |
String | Yes | All admins | If specified only audit log entries that occured on this date and time or before will be returned. A combined date/time in JavaScript’s standard ISO 8601-conforming format and with UTC as time zone is expected, i.e. “DDDD-MM-YYYY’T’HH:MM:SS.SSS’Z’“, for example “2019-03-19T13:41:11.257Z”. |
action |
String | Yes | All admins | If specified only audit log entries that apply to actions of this kind will be returned. |
entity |
String | Yes | All admins | If specified only audit log entries that apply to entities of this kind will be returned. |
page |
Int | Yes | All admins | Response is divided into multiple pages to avoid timeout. Frontend calls for specific page number. If not specified, defaults to 1. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Audit log entries are returned as a JSON array of objects as described below. |
| 400 (Bad request) | The request failed because an invalid parameter was supplied, for example an invalid date. Inspect the returned error message for details. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the calling admin’s organisation has been disabled. |
If the request was successful, a JSON object with following fields is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
entries |
List | All admins | List containing single “page” of audit log entries. |
pages |
Int | All admins | Total pages to be retrieved. |
Etries objects have following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
identifier |
String | All admins | The audit log entry’s ID. |
date |
String | All admins | Date and time of the audit log entry, i.e. when the event behind it occured. A combined date/time in JavaScript’s standard ISO 8601-conforming format and with UTC as time zone will be returned, i.e. “DDDD-MM-YYYY’T’HH:MM:SS.SSS’Z’“, for example “2019-03-19T13:41:11.257Z”. |
initiator |
String | All admins | The initiator of the audit log entry. Usually the user or admin (together with her remote IP address) who triggered the event but the string may also be empty or contain a string such as “n/a” if no particular initiator could be determined. |
affected_organisation |
String | All admins | The name of the organisation for which the audit log entry was generated. |
action |
String | All admins | The action behind this audit log entry, e.g. “Login” for a login event. |
entity |
String | All admins | The type of the entity behind this audit log entry, e.g. “Admin” for an event related to an admin. |
name |
String | All admins | The particular entity behind this audit log entry, e.g. “Alex Admin alex.admin@teamwire.eu” for an event related to such an admin. |
description |
String | All admins | A text containing details of the audit log entry, e.g. “Superadmin authenticated” if a Superadmin logged in. May contain newlines and Markdown-style lists. |
Please note that the values and formatting of the identifier,
initiator, affected_organisation and name fields is not
specified and may change at any time. Your code should thus not
make any assumptions about them but treat them as-is.
Likewise the set of possible values for the action and entity
fields is not fixed and may be extended in the future. If designing
a UI that allows specifying a filter for these fields, you should
thus not work with dropboxes alone but always allow the user to
specify a string manually to be compatible with future releases.