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.

Before you begin

• You need your Totango API token key. 
• For US services, please use https://api.totango.com
• For EU services, please use https://api-eu1.totango.com 
• 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.

Access audit log information

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.

Query can only be within a one year period. If you must do across a year span, request logs.

Use this syntax to download the audit log:

curl -X GET '<domain for US or EU>/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:abcdefghijklmnopqrstuvwxyz'

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, filter the audit information and get the desired portion of the information.

Available Filters (optional)

• 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".
• startDate and endDate - filter the audit information per the actions' date (format: YYYY-MM-DD). 
  Note: Start and End years must be equal.

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:

Views a user profile

• user_id of the end-user (on your system) which was viewed.
• Flag if user-profile includes sensitive data

Changes the value of a user attribute

• Id of the end user (on your system) for which an attribute value was changed
• Id of the changed attribute
• New value for attribute
• Flag if the attribute is marked as sensitive

In case a bulk change was performed, the user_id field will be replaced with the value “BULK”.

Views an account profile

• Account ID that was viewed

Edits an account attribute

• ID of the account (or BULK)
• ID of the changed attribute
• New value of attribute

In case a bulk change was performed, the account_id field will be replaced with the value “BULK”.

Totango user added

• ID of the Totango user added

Totango user added from a team

• ID of the Totango user changed
• Teams they are assigned to (after the change)

Totango user removed from a team

• ID of the Totango user changed
• Teams they are assigned to (after the change)

User attribute definition is updated

Whenever the definition of an attribute is changed in the system

• Attribute-name
• attribute-type
• sensitive on/off

Account attribute definition is updated

Whenever the definition of an attribute is changed in the system

• Attribute-name
• attribute-type

User segment is viewed

• Flag indicating if a sensitive field was added to the columns list

Account segment is viewed

User segment is exported via CSV

• id/name of segment (if exist)
• Flag indicating if a sensitive field was added to the columns list

Account segment is exported via CSV

Audit log viewed

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 Data Modeler.