Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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 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 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
.
This page describes how to update policies using the Policy Handler API.
dataSourceId
(integer): ID of the data source the policy will be applied to.
Example: 1
jsonRules
(array[object]): Array of JSON rules objects.
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:
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.
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.
Note: When adding conditions to a masking policy rule, the field
will be left blank, and the condition value
should be populated.
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.
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.
Note: When adding conditions to a minimization policy rule the field
will be left blank.
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.
Note: When adding conditions to a time based policy rule the field
will be left blank.
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.
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.
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:
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
.
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.
Support for the audit endpoint and UI has been deprecated. Instead, and push them to your SIEM.
.
.
.
.
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
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 |
---|
Method | Path | Purpose |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Attribute | Description | Required |
---|
Attribute | Description |
---|
Method | Path | Successful Status Code |
---|
The create policy handler endpoint must be a .
Method | Path | Successful Status Code |
---|
The update policy handler endpoint must be a .
Example: See
Example: See
Example: See
Example: See
When using a masking rule, there is an additional field that needs to be sent in the in the policyHandler.maskingConfiguration
array field.
Example: See
Example: See
When using a minimization rule, there is an additional field that needs to be sent in the in the policyHandler.additionalFilters.minimization
field.
Example: See
When using a time based rule, there is an additional field that needs to be sent in the in the policyHandler.additionalFilters
field.
Example: See
Example: See
.
.
.
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.
searchText
string
Used to filter returned schemas. The query is executed with a wildcard prefix and suffix.
No
values
metadata
The name
and count
for each result.
name
string
The name of the schema.
count
integer
The total number of data sources attached to that schema.
searchText |
| No |
values |
|
dataSourceId |
| No |
projectId |
| No |
profileId |
| No |
recordType |
| No |
outcome |
| No |
minDate |
| No |
maxDate |
| No |
blobId |
| No |
purpose |
| No |
offset |
| No |
size |
| No |
sortField |
| No |
sortOrder |
| No |
hits |
|
recordId |
| Yes |
hits |
|
recordId |
| Yes |
value |
|
dataSourceId |
| Yes |
offset |
| No |
size |
| No |
sortField |
| No |
sortOrder |
| No |
auditId |
|
query |
|
lastRun |
|
timesRun |
|
name |
|
groupByEntity |
| No |
profileId |
| No |
groupId |
| No |
name |
| No |
| No |
modelName |
| No |
modelTypes |
| No |
size |
| No |
sortField |
| No |
sortOrder |
| No |
offset |
| No |
hits |
|
count |
|
modelType |
| Yes |
modelId |
| Yes |
profileId |
| No |
groupId |
| No |
records |
|
id |
| Yes |
expiration |
| No |
id |
|
model |
|
entity |
|
requestIds |
| Yes |
id |
| Yes |
type |
| Yes |
success |
|
id |
| Yes |
denialReasoning |
| Yes |
id |
|
model |
|
entity |
|
requestIds |
| Yes |
id |
| Yes |
type |
| Yes |
denialReasoning |
| Yes |
success |
|
POST |
| 200 |
PUT |
| 200 |
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 |
GET | Get pending access requests the calling user can approve. |
GET | Get pending request information for specified model and requesting user (or specified entity). |
POST | Approve specified access requests. |
POST | Bulk approve access requests. |
POST | Deny specified access requests. |
POST | Bulk deny access requests. |
POST |
|
POST or PUT |
|
POST |
|
PUT |
|
POST |
|
GET |
|
GET |
|
GET |
|
GET |
|
GET |
|
GET |
|
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.
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.
.
.
.
.
.
.
.
.
.
.
.
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
Attribute | Description | Required |
---|---|---|
Attribute | Description |
---|---|
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.
body
string
Lists the bucket, organization, and owner of the bucket.
bucket
string
Name of the bucket (this should match the bucket name in configuration).
Yes
prefix
string
The prefix to start a search under.
No
max-keys
number
Max number of content objects to return.
No
delimiter
string
The terminating character for a search.
No
marker
string
When provided, only prefixes after this marker will be returned.
No
location
string
If provided, will instead return the bucket location.
No
encoding-type
string
Encoding type for content keys.
No
list-type
integer
If set to 2
, will use v2 of the API response.
No
fetch-owner
boolean
When true
, will return owner field in v2 API response.
No
start-after
string
Only prefixes after this marker will be returned. (This is the v2 API version of marker
).
No
body
string
Lists the data sources and/or data source blobs in the bucket.
bucket
string
Name of the bucket (this should match the bucket name in configuration).
Yes
dataSource
string
Immuta S3 Folder to search in.
Yes
key
string
Key path to search for the specified file.
Yes
body
string
Lists the data sources and/or data source blobs in the bucket.