Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This page describes the subscription
endpoint, which allows you to view and manage access requests.
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
GET
/subscription/getPendingRequestsForUser
Get pending access requests the calling user can approve.
The following request gets pending access requests the calling user can approve.
GET
/subscription/requestInfo/{modelType}/{modelId}
Get pending request information for specified model and requesting user (or specified entity).
The following request gets pending access requests for the data source with the ID 6
for the current user.
POST
/subscription/approve
Approve specified access requests.
The following request approves the subscription request.
POST
/subscription/approve/bulk
Bulk approve access requests.
The following request approves all of the subscription requests.
POST
/subscription/deny
Deny specified access requests.
The following request denies the subscription request.
POST
/subscription/deny/bulk
Bulk deny access requests.
The following request with the payload below denies the subscription requests with the IDs 40
and 41
.
The policy
endpoint allows you to manage and review policies in Immuta. This page outlines the endpoint and its request and response parameters.
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
POST
/policy/global
Create a Global Policy with a given entityType
.
When successful, the response returns the body of the request payload.
This example request creates a Global Policy (saved in the example-payload.json
file) in the Immuta tenant.
Request payload example
POST
or PUT
/policy/handler/{dataSourceId}
Create (POST) or update (PUT) a policy for the specified data source.
This example request applies the policy specified in the payload to the data source with the ID 2
.
Request payload example
Note: Global policies that contain the condition "with columns tagged" or "on all data sources" will automatically apply to relevant data sources when the policy is created. The endpoint detailed below can be used to apply Global Policies that contain the condition "when selected by data owners," as these policies are not automatically applied to data sources.
POST
/policy/global/applyPolicy
Apply the Global Policy to the specified data source.
None. When successful, no message will display.
This example request applies the specified Global Policy to the specified data source (saved in the example-payload.json
file) in the Immuta tenant.
Request payload example
The following payload will apply the Global Policy with the ID 1
to the data source with ID 1
.
PUT
/policy/global/{policyId}
Update the specified policy.
When successful, the response returns the body of the request payload.
This example request updates the specified Global Policy (8
) with changes to the metadata saved in the example-payload.json
file.
Request payload example
In this payload, the user updated the description
attribute to update the policy.
POST
/policy/search
Searches for specified policies.
This example request searches for a Global Policy that contains the text mask
in Immuta.
GET
/policy/global/{policyId}
Find the policy with the specified ID.
This example request returns the Global Policy with the ID 1
.
GET
/policy/global
Find the policy with the specified entity type.
This example request returns the name, type, and ID of all policies.
GET
/policy/global/appliedTo/{policyId}
Find the number of data sources the specified policy applies to.
This example request returns the number of data sources the Global Policy with the ID 6
applies to.
GET
/policy/dataSourcePolicies/{dataSourceId}
Get the policy information for the specified data source.
This example request returns the information of policies applied to the data source with the ID 2
.
GET
/policy/diff/{dataSourceId}
Get the differences between two policy handler versions.
This example request returns the information of policies applied to the data source with the ID 3
.
GET
/policy/handler/{dataSourceId}
Get the policy handler metadata for a specific data source.
This example request returns the policy handler metadata for policies applied to the data source with the ID 1
.
DELETE
/policy/global/{policyId}
Delete the specified Global Policy.
The following request deletes the Global Policy with ID 6
.
Method | Path | Purpose |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Method | Path | Purpose |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Method | Path | Purpose |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Policies can also be created and managed using the .
: Manage and review data and subscription policies in Immuta.
: Create and manage a domain.
: View and manage data source and project access requests.
: View examples of policy handler objects.
: Search Immuta audit logs.
: Search by connection string.
: Search by organization.
: Search S3 buckets.
: Search by schema.
.
.
.
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
See the for payload examples and details.
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
Attribute | Description | Required |
---|
See the for payload examples and details.
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
The response returns a .
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
The response returns a of the policy that was deleted.
GET
Get pending access requests the calling user can approve.
GET
Get pending request information for specified model and requesting user (or specified entity).
groupByEntity
boolean
If true
, group request results by user/group.
No
profileId
integer
Match against profile ID.
No
groupId
integer
Match against group ID.
No
name
string
A partial name to match against user or group names.
No
string
A partial email address to match against user or group email addresses.
No
modelName
string
A partial name to match against model names.
No
modelTypes
array[string]
Model types to include.
No
size
integer
The max number of matches to return. Default 15.
No
sortField
string
The field to sort results on. Defaults to name.
No
sortOrder
string
The order that the results will be sorted in. Default asc
.
No
offset
integer
Offset to start returning values.
No
hits
array
Metadata details regarding the access requests.
count
integer
The number of access requests.
modelType
string
The model that a pending request is out for. Options are datasource
or project
.
Yes
modelId
integer
The data source or project ID.
Yes
profileId
integer
A user ID if you want to get pending requests for another user.
No
groupId
integer
A group ID if you want to get pending requests for a whole group.
No
records
array
Details about each of the pending access requests, including subscriptionId
, requiredPermission
, state
, approverId
, ownerModelId
, approver
, and ownerModelName
.
POST
Approve specified access requests.
POST
Bulk approve access requests.
id
integer
The subscription ID of the request to approve.
Yes
expiration
date
The date to expire this user's access.
No
id
integer
If the request fails, the response includes the ID of the access request.
model
array[object]
If the request fails, the response includes details about the data source or project.
entity
array[object]
If the request fails, the response includes details about the user making the subscription request.
requestIds
integer
A list of the access request IDs to be approved. If requestIds
is provided, jobs will only be created for the IDs listed. Otherwise, the id
and type
values will be used to find and create jobs for all approval requests.
Yes
id
integer
The ID for the type
. If requestIds
is provided, jobs will only be created for the IDs listed. Otherwise, the id
and type
values will be used to find and create jobs for all approval requests.
Yes
type
string
The type of ID: profile
. If requestIds
is provided, jobs will only be created for the IDs listed. Otherwise, the id
and type
values will be used to find and create jobs for all approval requests.
Yes
success
boolean
If true
, all of the access requests have been successfully approved.
POST
Deny specified access requests.
POST
Bulk deny access requests.
id
integer
The subscription ID of the request to deny.
Yes
denialReasoning
string
The reason the user is denied access to the data source or project.
Yes
id
integer
If the request fails, the response includes the ID of the access request.
model
array[object]
If the request fails, the response includes details about the data source or project.
entity
array[object]
If the request fails, the response includes details about the user making the subscription request.
requestIds
integer
A list of the access request IDs to be approved. If requestIds
is provided, jobs will only be created for the IDs listed. Otherwise, the id
and type
values will be used to find and create jobs for all denial requests.
Yes
id
integer
The ID for the type
you select. If requestIds
is provided, jobs will only be created for the IDs listed. Otherwise, the id
and type
values will be used to find and create jobs for all denial requests.
Yes
type
string
The type of ID: profile
. If requestIds
is provided, jobs will only be created for the IDs listed. Otherwise, the id
and type
values will be used to find and create jobs for all denial requests.
Yes
denialReasoning
string
The reason that you are denying the access requests.
Yes
success
boolean
If true
, all of the access requests have been successfully denied.
body |
| Yes |
dataSourceId |
| Yes |
jsonPolicies |
| Yes |
id |
|
url |
|
dataSourceId |
|
createdBy |
|
ca |
|
jsonPolicies |
|
rules |
|
createdAt |
|
updatedAt |
|
payload |
| Yes |
policyID |
| Yes |
dataSourceID |
| Yes |
merged |
| Yes |
policyID |
| Yes |
payload |
| Yes |
body |
| No |
type |
| No |
scope |
| No |
size |
| No |
offset |
| No |
sortField |
| No |
sortOrder |
| No |
searchText |
| No |
countOnly |
| No |
mode |
| No |
excludedPolicies |
| No |
Count |
|
Hits |
|
policyId |
| Yes |
offset |
| No |
size |
| No |
sortField |
| No |
sortOrder |
| No |
searchText |
| No |
type |
| No |
scope |
| No |
nameOnly |
| No |
templates |
| No |
name |
|
id |
|
type |
|
hits |
|
policyId |
| Yes |
count |
|
dataSourceId |
| Yes |
retrieveAll |
| No |
excludeGlobal |
| No |
body |
|
dataSourceId |
| Yes |
previousHandlerId |
| No |
currentHandlerId |
| No |
current |
|
previous |
|
hasChanges |
|
dataSourceId |
| Yes |
hits |
|
policyId |
| Yes |
POST |
|
POST or PUT |
|
POST |
|
PUT |
|
POST |
|
GET |
|
GET |
|
GET |
|
GET |
|
GET |
|
GET |
|
This page describes how to update policies using the Policy Handler API.
The create policy handler endpoint must be a policy handler object.
The update policy handler endpoint must be a policy handler object.
dataSourceId
(integer): ID of the data source the policy will be applied to.
Example: 1
jsonRules
(array[object]): Array of JSON rules objects.
Example: See defining policy rules
The jsonRules
array contains rules objects. The following types of policy rules are supported:
Not all combination of policy rules are valid. The examples below are supported policy rule combinations:
Prerequisite, Visibility, Masking
Prerequisite, Masking, Minimization
Prerequisite policies are used to limit usage to one or more purposes.
type
(string): Policy rule type. Must be prerequisite
for prerequisite policy rules.
Example: "prerequisite"
operator
(string): Operator to be applied on conditions. Possible values: and, or.
Example: "or"
conditions
(array[object]): Conditions to be applied for the rule. Multiple values will be evaluated according to the operator.
Example: See purpose condition object
Example:
In this example, users will only have access to data from this data source when they are acting under the purpose
named Purpose Name
.
Visibility policies are used to enforce row-level security.
type
(string): Policy rule type. Must be visibility
for row-level security policy rules.
Example: "visibility"
operator
(string): Operator to be applied on conditions. Possible values: and, or.
Example: "or"
conditions
(array[object]): Conditions to be applied for the rule. Multiple values will be evaluated according to the operator.
Example: See policy conditions
Note: When adding conditions to a visibility policy rule, the field
is required, and the condition value
should be left empty. For example, for a group policy condition, the group name is not specified.
The user must possess the group, attribute, or purpose that matches the value stored in the field
.
Example:
In this example, users will only see rows when they have an authorization
that matches the value in the field department
and they belong to a group
that matches the value in the field organization
.
Masking policy rules will mask the value in one or more columns.
type
(string): Policy rule type. Must be masking
for masking policy rules.
Example: "masking"
fields
(array[string]): Fields that will be masked when a user does not fulfill policy conditions.
Example: ["email", "location"]
operator
(string): Operator to be applied on conditions. Possible values: and, or.
Example: "or"
conditions
(array[object]): Conditions to be applied for the rule. Multiple values will be evaluated according to the operator.
Example: See policy conditions
Note: When adding conditions to a masking policy rule, the field
will be left blank, and the condition value
should be populated.
When using a masking rule, there is an additional field that needs to be sent in the update data source request in the policyHandler.maskingConfiguration
array field.
name
(string): Name of the field being masked.
Example: "social"
type
(string): Type of masking to apply. Supported values are "Consistent Value"
, "Grouping"
, "Regular Expression"
Example: "Consistent Value"
metadata
(object): Extra metadata used when masking the value.
Example: See masking configuration metadata
Consistent value
constant
(string|null): Constant value to mask to. If this field is not defined, the value will be hashed.
Example: "REDACTED"
Regular expression
regex
(string): Regex to match against when masking columns.
Example: "[0-9]{3}-[0-9]{2}"
replacement
(string): String used to replace the matched regex.
Example: "xxx-xx"
Grouping
bucketSize
(integer): For number fields. Size of buckets to round numbers to.
Example: 100
timePrecision
(string): For time fields. Time precision to round to. Possible values: "MIN"
, "HOUR"
, "DAY"
, "WEEK"
, "MONTH"
, "YEAR"
Example: "HOUR"
Example policy handler update with masking configuration metadata:
Example:
In this example, the fields email
and location
will be masked unless the user belongs to the group admins
.
Minimization policy rules will show a limited percentage of the data, based on a high cardinality column, for everyone unless the user fulfills the policy conditions.
type
(string): Policy rule type. Must be additional
for minimization policy rules.
Example: "additional"
name
(string): Name of additional policy. Must be minimization
for minimization policy rules.
Example: "minimization"
operator
(string): Operator to be applied on conditions. Possible values: and, or.
Example: "or"
conditions
(array[object]): Conditions to be applied for the rule. Multiple values will be evaluated according to the operator.
Example: See policy conditions
Note: When adding conditions to a minimization policy rule the field
will be left blank.
When using a minimization rule, there is an additional field that needs to be sent in the update data source request in the policyHandler.additionalFilters.minimization
field.
percent
(integer): Percentage of the data to show to the users. This percentage will be based off of unique values in the hashPhrase
column.
Example: 50
hashPhrase
(string): Column to base the percentage off of. This should be a high cardinality column in the data source.
Example: "name"
Example policy handler rule:
In this example, 50 percent of the data, based on the name
field, will be visible to users unless they fulfill the policy conditions.
Example data source update (partial):
Time-based rules will make a limited portion of the data available based on event time. The data source must contain an event time column in order for this policy type to be valid. For instance, users who do not fulfill the policy conditions will only see data from within the defined time window.
type
(string): Policy rule type. Must be additional
for minimization policy rules.
Example: "additional"
name
(string): Name of additional policy. Must be time
for time based policy rules.
Example: "time"
operator
(string): Operator to be applied on conditions. Possible values: and, or.
Example: "or"
conditions
(array[object]): Conditions to be applied for the rule. Multiple values will be evaluated according to the operator.
Example: See policy conditions
Note: When adding conditions to a time based policy rule the field
will be left blank.
When using a time based rule, there is an additional field that needs to be sent in the update data source request in the policyHandler.additionalFilters
field.
time
(integer): Age in seconds of the oldest data a user will be allowed to see. This counts backward from the present.
Example: 14400
Example policy handler rule:
In this example, only data from the last 4 hours will be visible to users unless they fulfill the policy conditions.
Example data source update (partial):
There are three types of policy conditions:
The group policy condition restricts access to the condition when a user is a member of a group.
type
(string): Type of policy condition. Must be "groups"
for the group policy condition.
Example: "groups"
group
(object): Object describing group user must belong to in order to satisfy the policy condition.
Example: See group object
field
(string): Data field to match group name against when checking policy.
Example: "department"
Example:
name
(string): Name of group user must belong to in order to satisfy the policy condition.
Example: "users"
iam
(string): ID of the IAM containing the group.
Example: "active_directory"
The attribute policy condition restricts access to the condition when a user possesses an attribute.
type
(string): Type of policy condition. Must be "authorizations"
for the attribute policy condition.
Example: "authorizations"
authorization
(object): Object describing attribute user must possess in order to satisfy the policy condition.
Example: See group object
field
(string): Data field to match attribute value against when checking policy.
Example: "department"
Example:
auth
(string): Name of attribute to check for attribute value.
Example: "accesses"
value
(string): Value of attribute user must possess in order to satisfy the policy condition.
Example: "PII"
iam
(string): ID of the IAM user must receive the attribute from.
Example: "active_directory"
The purpose policy condition restricts access to the condition when a user is acting under a purpose.
type
(string): Type of policy condition. Must be "purposes"
for the purpose policy condition.
Example: "purpopses"
value
(string): Purpose name user must be acting under in order to satisfy the policy condition.
Example: "Purpose"
field
(string): Data field to match purpose name against when checking policy.
Example: "department"
Example:
Support for the audit endpoint and UI has been deprecated. Instead, pull audit logs from Kubernetes and push them to your SIEM.
This page describes the audit
endpoint API. The audit API allows users to programmatically search for audit records in Immuta.
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
GET
/audit
Search for audit records.
The following request searches for all audit records.
GET
/audit/{recordId}
Retrieve a specific audit record.
The following request retrieves a specific audit record.
GET
/audit/apikey/activity
Queries for the recent activity using the API key.
The following request queries for the recent activity using the API key.
GET
/audit/queries/dataSource/{dataSourceId}/mine
Returns the list of the current user's distinct queries for the specified data source.
The following request returns the list of the current user's distinct queries.
This page describes the organizations
endpoint.
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
GET
/organizations
Search for organizations.
The following request searches for organizations that contain Immuta
in their name.
This page describes the connectionStrings
endpoint.
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
GET
/connectionStrings
Search across all connection strings in the handler table.
The following request searches across all connection strings in the handler table.
This page describes the schemas
endpoint of the Immuta API and its request and response parameters.
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
GET
/schemas
Search across all schemas in the handler table.
This example request gets all of the schemas with the string "medical" in their name.
These endpoints allow you to communicate with Immuta the same way you would with S3, making Immuta easy to integrate with tools you may already be using to work with S3. In this integration, Immuta implements a single bucket (with data sources broken up as sub-directories under that bucket), since some S3 tools only support the new virtual-hosted style requests.
The endpoints outlined below support basic AWS functionality; the requests and responses for each are identical to those in S3.
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
GET
/s3p
Return constant bucket that all data sources are grouped under.
The following request returns the bucket all data sources are grouped under for the organization.
The following response lists the bucket immuta
.
GET
/s3p/{bucket}
Return the contents of a given bucket (data sources or data source blobs).
The following request returns a list of data sources in the bucket immuta
.
The following response lists the data source blob immuta
.
GET
/s3p/{bucket}/{dataSource}/{key}
Return a specific blob.
The following request returns the contents of the single file that exists in the requested directory in immuta
.
The following response lists the size, storage class, owner, and the last date of modification of the single file.
.
.
.
.
.
.
.
.
.
.
.
Method | Path | Successful Status Code |
---|---|---|
Method | Path | Successful Status Code |
---|---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
.
.
.
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
POST
/policy/handler
200
PUT
/policy/handler
200
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
hits
metadata
Details regarding the returned list of audits.
recordId
string
The audit record ID.
Yes
hits
metadata
Details regarding the returned audit record.
recordId
string
The audit record ID.
Yes
value
metadata
regarding the recent activity.
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
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.
searchText
string
A string used to filter returned organizations. The query is executed with a wildcard prefix and suffix.
No
name
string
The name of the organization.
searchText
string
A string used to filter returned connection strings. The query is executed with a wildcard prefix and suffix.
No
values
array
Details regarding connection strings, including name
and count
.
searchText |
| No |
values |
|
name |
|
count |
|
body |
|
bucket |
| Yes |
prefix |
| No |
max-keys |
| No |
delimiter |
| No |
marker |
| No |
location |
| No |
encoding-type |
| No |
list-type |
| No |
fetch-owner |
| No |
start-after |
| No |
body |
|
bucket |
| Yes |
dataSource |
| Yes |
key |
| Yes |
body |
|