Audit API Reference Guide

This page describes the audit endpoint API. The audit API allows users to programmatically search for audit records in Immuta.

Note

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Workflow

Search all audit records.
Retrieve a specific audit record.
Search for recent activities using the API key.
Search for queries for a specific data source.

Search for audit records

EndpointQuery ParametersResponse Parameters

Endpoint

Method	Path	Purpose
GET	`/audit`	Search for audit records.

Query Parameters

Attribute	Description	Required
dataSourceId	`array[integer]` The data source ID.	No
projectId	`array[integer]` The project ID.	No
profileId	`array[integer]` The user profile ID.	No
recordType	`array[integer]` The type of audit event being captured. This also corresponds to the additional information in the record field.	No
outcome	`Array[integer]`	No
minDate	`timestamp` The minimum date.	No
maxDate	`timestamp` The maximum date.	No
blobId	`string` The blob ID.	No
purpose	`integer`	No
offset	`integer` Used in combination with `size` to fetch pages.	No
size	`integer` Pages results by default; `size` is the number of results to return per page. Default `50`	No
sortField	`string` Sorts results by field. Default `dateTime`	No
sortOrder	`string` Sorts results by order, which must be `asc` or `desc`. Default `desc`	No

Response Parameters

Attribute	Description
hits	`metadata` Details regarding the returned list of audits.

Request example

The following request searches for all audit records.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/audit?size=2&sortField=dateTime&sortOrder=desc

Response example

{
  "hits": [
    {
      "dateTime": "1632756753272",
      "dataSourceName": null,
      "projectName": null,
      "recordType": "auditQuery",
      "blobId": null,
      "userId": "first.last@immuta.com",
      "profileId": 2,
      "purposeIds": null,
      "success": true,
      "failureReason": null,
      "id": "480d9d3f-4128-445d-8eec-3cccb34f9935",
      "fingerprintVersionName": null,
      "email": "first.last@immuta.com"
    },
    {
      "dateTime": "1632755783628",
      "dataSourceName": null,
      "projectName": null,
      "recordType": "authenticate",
      "blobId": null,
      "userId": "first.last@immuta.com",
      "profileId": 2,
      "purposeIds": null,
      "success": true,
      "failureReason": null,
      "id": "d143719b-6af9-4af3-aa99-8055be40e877",
      "fingerprintVersionName": null,
      "email": "first.last@immuta.com"
    }
  ],
}

Retrieve a specific audit record

EndpointQuery ParametersResponse Parameters

Endpoint

Method	Path	Purpose
GET	`/audit/{recordId}`	Retrieve a specific audit record.

Query Parameters

Attribute	Description	Required
recordId	`string` The audit record ID.	Yes

Response Parameters

Attribute	Description
hits	`metadata` Details regarding the returned audit record.

Request example

The following request retrieves a specific audit record.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/audit/480d9d3f-4128-445d-8eec-3cccb34f9935

Response Example

{
  "id": "480d9d3f-4128-445d-8eec-3cccb34f9935",
  "dateTime": "1632756753272",
  "month": 1460,
  "profileId": 2,
  "userId": "first.last@immuta.com",
  "dataSourceId": null,
  "dataSourceName": null,
  "projectId": null,
  "projectName": null,
  "purposeIds": null,
  "policyId": null,
  "policyName": null,
  "fingerprintVersionId": null,
  "fingerprintVersionName": null,
  "count": 1,
  "recordType": "auditQuery",
  "success": true,
  "failureReason": null,
  "failureDetails": null,
  "subscriptionState": null,
  "accessedId": null,
  "accessedIdType": null,
  "accessedIamId": null,
  "accessedUserId": null,
  "groupAccessType": null,
  "groupIamId": null,
  "accessedGroupId": null,
  "component": "audit",
  "accessType": null,
  "blobId": null,
  "query": null,
  "queryId": null,
  "extra": {
    "params": {
      "size": 50,
      "sortField": "dateTime",
      "sortOrder": "desc",
      "offset": 0
    }
  },
  "dataSourceSchemaName": null,
  "dataSourceTableName": null,
  "featureKey": null,
  "sqlUser": null,
  "action": null,
  "blobSize": null,
  "hardDelete": null,
  "keyAction": null,
  "keyId": null,
  "keyIamId": null,
  "keyUserId": null,
  "createdAt": "2021-09-27T15:32:33.274Z",
  "updatedAt": "2021-09-27T15:32:33.274Z"
}

Query for activity by API key

EndpointQuery ParametersResponse Parameters

Endpoint

Method	Path	Purpose
GET	`/audit/apikey/activity`	Queries for the recent activity using the API key.

Query Parameters

Attribute	Description	Required
recordId	`string` The audit record ID.	Yes

Response Parameters

Attribute	Description
value	`metadata` regarding the recent activity.

Request example

The following request queries for the recent activity using the API key.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/audit/apikey/activity?keyid=650&count=1

Response example

{
  "id": "480d9d3f-4128-445d-8eec-3cccb34f9935",
  "dateTime": "1632756753272",
  "month": 1460,
  "profileId": 2,
  "userId": "first.last@immuta.com",
  "dataSourceId": null,
  "dataSourceName": null,
  "projectId": null,
  "projectName": null,
  "purposeIds": null,
  "policyId": null,
  "policyName": null,
  "fingerprintVersionId": null,
  "fingerprintVersionName": null,
  "count": 1,
  "recordType": "auditQuery",
  "success": true,
  "failureReason": null,
  "failureDetails": null,
  "subscriptionState": null,
  "accessedId": null,
  "accessedIdType": null,
  "accessedIamId": null,
  "accessedUserId": null,
  "groupAccessType": null,
  "groupIamId": null,
  "accessedGroupId": null,
  "component": "audit",
  "accessType": null,
  "blobId": null,
  "query": null,
  "queryId": null,
  "extra": {
    "params": {
      "size": 50,
      "sortField": "dateTime",
      "sortOrder": "desc",
      "offset": 0
    }
  },
  "dataSourceSchemaName": null,
  "dataSourceTableName": null,
  "featureKey": null,
  "sqlUser": null,
  "action": null,
  "blobSize": null,
  "hardDelete": null,
  "keyAction": null,
  "keyId": null,
  "keyIamId": null,
  "keyUserId": null,
  "createdAt": "2021-09-27T15:32:33.274Z",
  "updatedAt": "2021-09-27T15:32:33.274Z"
}

Search for query list by data source

EndpointQuery ParametersResponse Parameters

Endpoint

Method	Path	Purpose
GET	`/audit/queries/dataSource/{dataSourceId}/mine`	Returns the list of the current user's distinct queries for the specified data source.

Query Parameters

Attribute	Description	Required
dataSourceId	`array[integer]` The data source ID.	Yes
offset	`integer` Used in combination with `size` to fetch pages.	No
size	`integer` Pages results by default; `size` is the number of results to return per page. Default `50`	No
sortField	`string` Sorts results by field. Default `dateTime`	No
sortOrder	`string` Sorts results by order, which must be `asc` or `desc`. Default `desc`	No

Response Parameters

Attribute	Description
auditId	`array[integer]` The audit ID.
query	`string` The query run for the data source.
lastRun	`integer` The date and time the query was last run in Unix.
timesRun	`integer` The number of times the audit has been run.
name	`string` The name of the query.

Request example

The following request returns the list of the current user's distinct queries.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/audit/queries/dataSource/23/mine?size=10&sortField=lastrun&sortOrder=desc

Response example

{
  "hits": [
    {
      "auditId": "ff264e8e-2ccc-468f-9129-bb0995c9cdf5",
      "query": "select * from \"public\".\"foobar\"",
      "lastrun": "1631627763345",
      "timesrun": "5",
      "name": "Name"
    },
    {
      "auditId": "f722042f-f0f3-4c83-bd33-7672892d918f",
      "query": "SELECT * FROM \"public\".\"foobar\" LIMIT 100",
      "lastrun": "1631200121550",
      "timesrun": "3",
      "name": null
    }
  ],
  "count": 2
}