The Audit API enables you to audit who viewed and who made changes to end-user PII data.
This API is mainly used for the purpose of complying with the GDPR, and other governance purposes.
Your Authentication Keys
You will need your API key in order to access the API.
Login to Totango, click on your username (top-right corner of the page) and open your user profile. Your API Key is available under the INTEGRATION tab
How To Access Audit Log Information?
You can access the audit log by using the audit API endpoint as shown below.
You will need to supply your API token, audit log start date, and audit log end date.
Use this syntax to download the audit log:
curl -X GET 'https://api.totango.com/api/v2/audit?startDate=<audit log start date>&endDate=<audit log end date>' -H 'app-token: < your API token>'
example:
curl -X GET 'https://api.totango.com/api/v2/audit?startDate=2018-04-29&endDate=2018-05-12' -H 'app-token:11112222333444aaaabbbbccccamit@abcd.com'
Please note, in order to export May 3rd audit log, you should define startDate=2018-05-03&endDate=2018-05-04.
Filter The Audit Log
To get answers to more specific questions from the Audit API, you are able to filter the audit information and get the desired portion of the information.
Available Filters:
- Action - filter the audit information per a user action (for example, "USER_PROFILE_VIEW"). The available actions are described in the table below.
User- filter the audit information by the user who performed the action. The user filter format is "user id"
Sensitive - filter the audit information to understand whether the information exposed was sensitive or not. To filter sensitive information use "sensitive=true".
example:
curl -X GET 'https://api.totango.com/api/v2/audit?startDate=2018-05-01&endDate=2018-05-30&action=USER_SEGMENT&user=amit@totango.com&sensitive=true' -H 'app-token:11112222333444aaaabbbbccccamit@abcd.com'
Audit Log Format
The audit returns a structured response. Each line in the response is a single log entry, structured in JSON format, as shown in the following example:
| {"action":"ACCOUNT_SEGMENT","ts":"2018-05-01 13:37:39.000","service_id":"007","totango_user":"avon@barksdale.com"} {"action":"USER_SEGMENT","ts":"2018-05-01 13:37:39.000","service_id":"007","totango_user":"avon@barksdale.com"} {"action":"ACCOUNT_SEGMENT","ts":"2018-05-01 13:37:39.000","service_id":"007","totango_user":"avon@barksdale.com"} {"action":"ACCOUNT_ATTRIBUTE_CHANGE","ts":"2018-05-01 13:52:07.000","service_id":"007","attribute_id":"Contract Renewal Date","new_attribute_value":"2020-03-31T08:00:00.000Z","totango_user":"avon@barksdale.com"} |
The following fields exists in every record:
- timestamp: The timestamp the action was performed
- action: The specific action performed by the user, according to the table below
- totango_user: the username on totango who performed the action
- service_id: The Totango service ID. This will always match the service of the authenticated user
In addition, certain actions may include additional fields as shown below:
|
Action |
Additional Information |
Example |
|
Views a user-profile |
|
{ "action":"USER_PROFILE_VIEW", "timestamp":"2018-05-03 07:22:30.000", "service_id":"1111111", "includes_sensitive_data":"false", "user_id":"someone@abcd.com", "totango_user":"amit@totango.com" } |
|
Changes the value of a user attribute |
|
{ "action":"USER_ATTRIBUTE_CHANGE", "timestamp":"2018-05-03 07:22:42.000", "service_id":"1111111", "includes_sensitive_data":"true", "User_id":"xxxxxx11111", “Account_id”:”22222222”, "attribute_id":"Email", "new_attribute_value":"boris@yeltzin.com", "totango_user":"amit@totango.com" } NOTE: In case a bulk change was performed, the user_id field will be replaced with the value “BULK” |
|
Views an account-profile |
|
{ "action":"ACCOUNT_PROFILE_VIEW", "timestamp":"2018-05-03 10:33:21.000", "service_id":"1111111" ,"account_id":"22222222", "totango_user":"amit@totango.com" } |
|
Edits an account-attribute |
|
{ "action":"ACCOUNT_ATTRIBUTE_CHANGE", "timestamp":"2018-05-03 07:23:18.000", "service_id":"1111111", "attribute_id":"Number of Licenses", "new_attribute_value":"1500", "totango_user":"amit@totango.com" } NOTE: In case a bulk change was performed, the account_id field will be replaced with the value “BULK” |
|
Totango user added |
|
{ "action":"TOTANGO_USER_ADDED", "timestamp":"2018-05-03 09:11:40.000", "service_id":"1111111", "totango_user":"amit@totango.com", "totango_user_added":"newly.added.user@totango.com" } |
|
Totango user added from a team |
|
{ "action":"TOTANGO_TEAM_ADDED", "timestamp":"2018-05-03 09:11:59.000", "service_id":"1111111", "team_id":"2222", "totango_user_changed_ids":"[\"aaa@totango.com\"]", "totango_user":"amit@totango.com" } |
|
Totango user removed from a team |
|
{ "action":"TOTANGO_TEAM_REMOVED", "timestamp":"2018-05-03 09:11:59.000", "service_id":"1111111", "team_id":"2222", "totango_user_changed_ids":"[\"aaa@totango.com\"]", "totango_user":"amit@totango.com" } |
|
User Attribute definition is updated |
Whenever the definition of an attribute is changed in the system
|
{ "action":"USER_ATTRIBUTE_UPDATED", "timestamp":"2018-05-03 11:28:32.000", "service_id":"1111111", "new_attribute_name":"Email", "new_attribute_type":"Text", "includes_sensitive_data":"true", "totango_user":"amit@totango.com" } |
|
Account Attribute definition is updated |
Whenever the definition of an attribute is changed in the system
|
{ "action":"ACCOUNT_ATTRIBUTE_UPDATED", "timestamp":"2018-05-03 11:28:32.000", "service_id":"1111111", "new_attribute_name":"Contract Value", "new_attribute_type":"Numeric", "totango_user":"amit@totango.com" } |
|
User segment is viewed |
|
{ "action":"USER_SEGMENT", "timestamp":"2018-05-03 08:35:40.000", "service_id":"1111111", "includes_sensitive_data":"true", "totango_user":"amit@totango.com" } |
|
Account segment is viewed |
{ "action":"ACCOUNT_SEGMENT", "timestamp":"2018-05-03 08:43:40.000", "service_id":"1111111", "totango_user":"amit@totango.com" } |
|
|
User segment is exported via CSV |
|
{ "action":"USER_SEGMENT_EXPORTED", "timestamp":"2018-05-03 08:55:10.000", "service_id":"1111111", "includes_sensitive_data":"true", "totango_user":"amit@totango.com" } |
|
Account segment is exported via CSV |
{ "action":"ACCOUNT_SEGMENT_EXPORTED", "timestamp":"2018-05-03 08:44:20.000", "service_id":"1111111", "totango_user":"amit@totango.com" } |
|
|
Audit Log Viewed |
{ "action":"AUDIT_FILE_EXPORTED", "timestamp":"2018-05-03 08:19:36.000", "service_id":"1111111", "includes_sensitive_data":"true", "totango_user":"amit@totango.com", "date_range":"{\"end_date\":\"2018-05-04\",\"start_date\":\"2018-05-03\"}" } |
Note: In order to determine if a Totango user had access to private / sensitive user data, look for the "includes_sensitive_data" field in log entries. Make sure all sensitive user fields are marked as such in the Global Settings | Attributes & Metrics
General restrictions and API limits
Like all APIs, there is a global rate limit of 1,000 calls/minute for each token.
It may take up to several minutes for entries to show up in the audit log after the action has been taken.
Audit log information is available from 3 May 2018