Report-Only Data

POST /auditlogs

Records activity for report-only data; that is, data that is not stored in the vault but is still being monitored. The purpose of this endpoint is to collect metadata about how sensitive data stored in external systems is being used.

While writes of external data can be recorded using the same API endpoint used for storing data in the vault, this endpoint allows recording reads and deletes as well as writes, as well as allowing more metadata to be expressed.

Parameters

Body Parameters (Required)

Name	Type	Description
payload	ExternalActivityEvent	Description of accesses to externally-stored data

The structure of the ExternalActivityEvent object is as follows:

Name	Type	Description	Usage
eventType	String	One of "READ", "STORE", "DELETE", or "UPDATE".	Required
dataPointId	String	Unique identifier for the attribute being accessed. This can be an identifier that is created externally or one that is generated by ViziVault.	Optional for `"STORE"` events (a new data point ID will be generated by ViziVault in this case); required for other events.
subjectId	String	Unique identifier for the data subject whom this attribute belongs to	Required for `"STORE"` events; optional for other events as it can be derived from the data point id.
data	Attribute	The attribute being saved for a `"STORE"` or `"UPDATE"` event.	For `"STORE"` events, `data` must contain `attribute`, and all other fields that would be used when storing data in the vault are optional. For `"UPDATE"` events, all fields of `data` other than `value` are ignored. In either case, if a value is supplied, it will be used by the rules engine but it will not be stored.
timestamp	Date	The time at which the access occurred. If not specified, the current time will be assumed.	Optional
applicationId	String	Unique identifier for the application that was used to initiate this access.	Required
applicationUser	String	Identifier for the application user who initiated this access.	Optional
dataStoreName	String	Identifier for a database in which this event happened.	Optional
dataStoreServer	String	Identifier for a database server on which this event happened.	Optional
dataStoreEntityName	String	Identifier for a collection or table within a database in which this event happened.	Optional
location	Geolocation	The geographic country, subdivision, and/or city where this access was initiated from.	Optional

Example payload

{
    "eventType": "STORE",
    "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce526",
    "subjectId": "user65536",
    "data": {
        "attribute": "SHIPPING_ADDRESS",
        "value": {
            "line_one": "1 Hacker Way",
            "city": "Beverly Hills",
            "state": "CA",
            "postal_code": "90210"
        },
        "tags": ["tag1", "tag2"],
        "regulations": ["COPPA", "GDPR"],
        "sensitivity": "SENSITIVE"

    },
    "timestamp": "2021-01-01T00:00:00Z",
    "applicationId": "5eabb29fac3675476ae1ec48",
    "applicationUser": "csmith97",
    "location": {
        "country": "US",
        "subdivision": "NY",
        "city": "Albany"
    }
}

Example response

On success, returns 200 OK and a summary of the accesses that were recorded, including newly-generated datapoint IDs for any newly-stored attributes that did not already have them.

{
    "eventType": "STORE",
    "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce526",
    "subjectId": "user65536",
    "attribute": "SHIPPING_ADDRESS",
    "subPoints": [
        {
            "attribute": "SHIPPING_ADDRESS.line_one",
            "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce626"
        },
        {
            "attribute": "SHIPPING_ADDRESS.city",
            "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce627"
        },
        {
            "attribute": "SHIPPING_ADDRESS.state",
            "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce628"
        },
        {
            "attribute": "SHIPPING_ADDRESS.postal_code",
            "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce629"
        }
    ]
}

Error responses

Status code	Error message	Description
400	Event type is required	The event type for an activity event was not specified.
400	Unrecognized event type	The event type for an activity event was something other than `READ`, `STORE`, `UPDATE`, or `DELETE`.
400	Data point ID is required for events other than creation	An activity event whose event type was not `STORE` had no datapoint ID specified.
409	Cannot create data point with ID, as there is already a point with that ID	A `STORE` event had a data point ID specified, but the system already contained an attribute with that datapoint ID
409	Attribute given for datapoint ID does not match attribute of existing point with that ID	An `UPDATE` event had an attribute definition specified that does not match the attribute being updated
409	Data subject ID given for datapoint ID does not match attribute of existing point with that ID	An `UPDATE` event had a data subject id specified that does not match the attribute being updated
400	No such attribute	You are attempting to report activity for data belonging to an attribute that does not exist.
422	Expected [type] for value of attribute [attribute]	The value provided for the indicated attribute or sub-attribute does not match what is expected according to that attribute's schema.
422	Unknown sub-attribute [sub-attribute]	A value provided for a structured attribute contains a sub-attribute that is not present in that attribute's schema.
400	Timestamp out of range	A timestamp was provided for the event that is more than one day in the future.
400	Application ID is required	The application ID was not specified.
403	The provided data could not be stored, as a rule disallows it	A rule has been configured that prohibits writing some of the data that was reported as having been stored.

POST /auditlogs/bulk

Identical to POST /auditlogs, but handles multiple events in one request.

Body Parameters (Required)

Name	Type	Description
payload	List<ExternalActivityEvent>	List of accesses to externally-stored data

Example payload

[
    {
        "eventType": "STORE",
        "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce526",
        "subjectId": "user65536",
        "data": {
            "attribute": "SHIPPING_ADDRESS",
            "value": {
                "line_one": "1 Hacker Way",
                "city": "Beverly Hills",
                "state": "CA",
                "postal_code": "90210"
            },
            "tags": ["tag1", "tag2"],
            "regulations": ["COPPA", "GDPR"],
            "sensitivity": "SENSITIVE"
        },
        "timestamp": "2021-01-01T00:00:00Z",
        "applicationId": "5eabb29fac3675476ae1ec48",
        "applicationUser": "csmith97",
        "location": {
            "country": "US",
            "subdivision": "NY",
            "city": "Albany"
        }
    },
    {
        "eventType": "READ",
        "subjectId": "user65536",
        "dataPointId": "1fbeb66e-d460-43f6-b474-164b2c5ce527",
        "timestamp": "2021-01-01T00:00:00Z",
        "applicationId": "5eabb29fac3675476ae1ec48",
        "applicationUser": "csmith97",
        "location": {
            "country": "US",
            "subdivision": "NY",
            "city": "Albany"
        }
    },
    {
        "eventType": "READ",
        "dataPointId": "1fbeb66e-d460-43f6-b474-164b2c5ce527",
        "applicationId": "5eabb29fac3675476ae1ec48"
    },
    {
        "eventType": "STORE",
        "subjectId": "user01024",
        "data": {
            "attribute": "BILLING_ADDRESS",
        },
        "applicationId": "5eabb29fac3675476ae1ec48"
    }
]

Example response

On success, returns 200 OK and a summary of the accesses that were recorded, including newly-generated datapoint IDs for any newly-stored attributes that did not already have them.

[
    {
        "eventType": "STORE",
        "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce526",
        "subjectId": "user65536",
        "attribute": "SHIPPING_ADDRESS",
        "subPoints": [
            {
                "attribute": "SHIPPING_ADDRESS.line_one",
                "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce626"
            },
            {
                "attribute": "SHIPPING_ADDRESS.city",
                "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce627"
            },
            {
                "attribute": "SHIPPING_ADDRESS.state",
                "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce628"
            },
            {
                "attribute": "SHIPPING_ADDRESS.postal_code",
                "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce629"
            }
        ]
    },
    {
        "eventType": "READ",
        "dataPointId": "1fbeb66e-d460-43f5-b473-164b2c5ce526",
        "subjectId": "user65536",
        "attribute": "SHIPPING_ADDRESS"
    },
    {
        "eventType": "READ",
        "dataPointId": "1fbeb66e-d460-43f6-b474-164b2c5ce527",
        "subjectId": "user01024",
        "attribute": "BILLING_ADDRESS"
    },
    {
        "eventType": "STORE",
        "dataPointId": "1fbeb66e-d460-43f6-b474-164b2c5ce527",
        "subjectId": "user01024",
        "attribute": "BILLING_ADDRESS",
    }
]

Error responses

Status code	Error message	Description
400	Event type is required	The event type for an activity event was not specified.
400	Unrecognized event type	The event type for an activity event was something other than `READ`, `STORE`, `UPDATE`, or `DELETE`.
400	Data point ID is required for events other than creation	An activity event whose event type was not `STORE` had no datapoint ID specified.
409	Data point ID is in use	A `STORE` event had a data point ID specified, but the system already contained an attribute with that datapoint ID that belonged to a different data subject ID and/or attribute definition
400	No such attribute	You are attempting to report activity for data belonging to an attribute that does not exist.
400	Expected [type] for value of attribute [attribute]	The value provided for the indicated attribute or sub-attribute does not match what is expected according to that attribute's schema.
400	Unknown sub-attribute [sub-attribute]	A value provided for a structured attribute contains a sub-attribute that is not present in that attribute's schema.
400	Timestamp out of range	A timestamp was provided for the event that is more than one day in the future.
400	Application ID is required	The application ID was not specified.
403	The provided data could not be stored, as a rule disallows it	A rule has been configured that prohibits writing some of the data that was reported as having been stored.