Audit HTTP API
Audience: Data Owners
Content Summary: The Audit API allows users to programmatically create Audit Records in Immuta.
Create Audit Record
Method | Path | Successful Status Code |
---|---|---|
POST | /audit/createRecord |
200 |
Request Path Parameters: General Details
profileId
(integer): The profile ID for the user generating the action.component
(string): Required The Immuta component used to perform the action. Available options areconsole
featureStore
dataSource
bim
audit
policy
project
plugin
governance
admin
tag
sqlUser
(string): The database user account performing the action. This parameter should only be used if the action is being performed using a database user account.dataSourceId
(integer): The data source ID of the accessed data source. This parameter should only be used if the action is associated with a data source.projectId
(integer): The project ID of the project used to access the data source. This parameter should only be used if the action is associated with a project.purposeIds
(integer): The purpose ID of the purpose used to access the data source. This parameter should only be used if the action is associated with a purpose.policyId
(integer): The policy ID of the policy. This parameter should only be used if the action is associated with a Global Policy.
Request Path Parameters: Data Access
dataAccess
(object): Describes access to an individual blob or a query that may grant access to data.accessType
(string): Indicates whether access was granted to an individual blob or if this was a query accessing data. Available options areblob
query
blobId
(string): The blob ID of the blob accesses. This parameter should be used whenaccessType
equalsblob
.query
(string): The query used to access data. This parameter should only be used whenaccessType
equalsquery
.dataSourceTableName
(string): The data source table name that was queried.
Action Result
success
(boolean): Required Denotes whether the action was successful.failureReason
(string): Describes the reason that the action failed. This parameter should only be used ifsuccess
isfalse
. Acceptable values aresystemError
insufficientAuthorizations
insufficientPermissions
userError
failureDetails
(string): Additional details about the failed action. This parameter should only be used ifsuccess
isfalse
.
Record Details
recordType
(string): Required The type of action being captured. Acceptable values areauditQuery
: anyone views, filters, or queries audit records in the Audit section of the UI.blobFetch
: a file is downloaded/viewed via the API.blobIndex
: a new file is discovered, either via API or scheduled crawl (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).blobDelete
: a file is removed from Immuta's index, either via API or scheduled crawl (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).blobUpdateTags
: a tag is added to a file, either via API or scheduled crawl (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).spark
: a query is executed via Spark.sqlCreateUser
: a Query Engine user account is created.sqlDeleteUser
: a Query Engine user account is deleted.sqlResetPassword
: a Query Engine user account password is reset.sqlQuery
: a query is executed via the Query Engine.dataSourceCreate
: a data source is created.dataSourceDelete
: a data source is disabled or deleted.dataSourceExpired
: a data source has expired.dataSourceSave
: a data source is updated.dataSourceSubscription
: a user is subscribed or unsubscribed from a data source.dataSourceTestQuery
: a health check query was run against the data source.dictionaryCreate
: a dictionary was created for a data source (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).dictionaryDelete
: a dictionary was deleted for a data source (relevant only for HDFS, FTP, Custom, Persisted, S3, and Azure Blob Store sources).dictionaryUpdate
: a dictionary was updated on a data source.projectCreate
: a project was created.projectPurposeApprove
: a project purpose was approved.projectPurposeDeny
: a project purpose was denied.projectUpdate
: a project was updated.projectDelete
: a project was disabled or deleted.addToProject
: a data source was added to a project.removeFromProject
: a data source was removed from a project.projectSubscription
: a user is subscribed or unsubscribed from a project.acknowledgePurposes
: a user acknowledged the purposes on a project.accessUser
: any change to a user's information (new attributes, groups, profile changes, or the user was disabled).accessGroup
: any change to a group.apiKey
: an API key was created or deleted or the metadata was queried.tagAdded
: a tag was added to a data source.tagCreated
: a user with GOVERNANCE permission created a new tag.tagDeleted
: a user with GOVERNANCE permission deleted a tag.tagUpdated
: a user with GOVERNANCE permission updated a tag.tagRemoved
: a tag was removed from a data source.authenticate
: a user logged in to Immuta.checkPendingRequest
: A user checked the status of a pending subscription requestpolicyExemption
: if policies exemptions are enabled and the user meets a policy exemption, this record is created when querying for data.purposeCreate
: a user with GOVERNANCE or PROJECT_MANAGEMENT creates a new purpose.purposeUpdate
: a user with GOVERNANCE or PROJECT_MANAGEMENT updates a purpose.purposeDelete
: a user with GOVERNANCE or PROJECT_MANAGEMENT deletes a purpose.licenseCreate
: a new license key is added to Immuta.licenseDelete
: a license key is deleted.policyAdjustmentCreate
: a policy adjustment is created (policy adjustments must be enabled).policyAdjustmentDelete
: a policy adjustment is deleted (policy adjustments must be enabled).policyAdjustmentExpired
: a policy adjustment expires (policy adjustments must be enabled).policyExport
: policies are exported (policy import/export must be enabled).policyImport
: policies are imported (policy import/export must be enabled).globalPolicyCertify
: a global policy is marked as Certified.policyCertificationExpired
: a global policy certification expires.globalPolicyCreate
: a global policy is created.globalPolicyUpdate
: a global policy is updated.globalPolicyDelete
: a global policy is deleted.globalPolicyDisabled
: a user disabled a global policy on a specific data source.globalPolicyApplied
: a global policy was applied to a data source.globalPolicyRemoved
: a global policy was removed from a data source.externalUserIdChanged
: a user's external user id (for native integrations) was changed.externalQuery
: a query record that is allowed to be created by an external system to signify in Immuta audit that a query occurred.unmaskRequest
: A request was made to unmask a column masked with a reversible (or format preserving masking) policy.queryDebugRequest
: a request was made to download debug information for a query.taskValidate
: a new column or data source was marked as validated.taskDelete
: an unmask request or query debug request was deleted.handleTask
: an unmask request or query debug request was completed.s3pBlobFetch
: a file is downloaded/viewed via the S3 access pattern.switchCurrentProject
: the user switches the current project.webhookCreate
: a webhook was created.webhookDelete
: a webhook was deleted.configurationUpdate
: the system-wide configuration was updated.driverUpload
: an ODBC driver was uploaded.workSpace
: a user accessed a file inside of a workspace.prestoQuery
: a query was executed natively in Presto against an Immuta data source.
record
(object): Describes the action being captured.blobSize
(integer): The size (in bytes) of the blob being fetched.sqlUser
(string): The username of the user whose access is being manipulated.action
(string): Denotes whether access was granted or revoked. Acceptable values arerevoked
granted
subscriptionState
(string): Indicates the state to which the record was changed. Acceptable values aredenied
subscribed
expert
owner
ingest
unsubscribed
accessedId
(integer): The user identifier of the user who is being acted upon.accessedIdType
(string): Type of user being acted upon. Acceptable values areuser
group
hardDelete
(boolean): Denotes whether this was a hard delete.expirationDate
(datetime): Denotes when the action expired in Immuta.accessType
(string): Denotes how the specified user was accessed. Acceptable values areupdate
get
search
create
delete
complete
newToken
clone
disable
accessedIamId
(string): The IAM ID for the user being accessed.accessedUserId
(string): The user being accessed.groupAccessType
(string): Denotes how the specified group was accessed. Acceptable values areupdate
get
search
create
delete
addUser
removeUser
groupIamId
(string): The IAM ID for the group being accessed.accessedGroupId
(integer): The group being accessed.keyAction
(string): The action taken on the API key. Acceptable values areget
delete
keyId
(integer): The API key ID.keyIamId
(string): The IAM ID for the user who owns the API key accessed.keyUserId
(string): The user who owns the API key accessed.
extra
(object): A JSON object representing the additional information to be logged/audited.
Response
The endpoint returns an object with a success array and failure array.
Example Requests
SQL Query: Data Source is Known:
{
"component": "featureStore",
"recordType": "externalQuery"
"profileId": 1,
"dataSourceId": 1,
"dataAccess": {
"accessType": "query",
"query": "SELECT * FROM my_data_source",
"dataSourceTableName": "my_data_source"
},
"success": true
}
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/audit/createRecord
SQL Query: Data Source and Project are Known:
{
"component": "featureStore",
"recordType": "externalQuery"
"profileId": 1,
"projectId": 1,
"dataSourceId": 1,
"dataAccess": {
"accessType": "query",
"query": "SELECT * FROM my_data_source",
"dataSourceTableName": "my_data_source"
},
"success": true
}
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/audit/createRecord
Failed SQL Query: Data Source and Project are Known:
{
"component": "featureStore",
"recordType": "externalQuery"
"profileId": 1,
"projectId": 1,
"purposeIds": [1],
"dataSourceId": 1,
"dataAccess": {
"accessType": "query",
"query": "SELECT * FROM my_data_source",
"dataSourceTableName": "my_data_source"
},
"success": false,
"failureReason": "insufficientPermissions",
"recordType": "sqlQuery"
}
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/audit/createRecord