Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Write policies API endpoint reference guide
The policies resource allows you to manage and apply policies to your data sources. The endpoints and examples provided in this guide are specific to creating global write policies.
POST
Manually grants write access to a user
POST
Creates a global write access policy
DELETE
Deletes the specified global write access policy
GET
Gets the global policy with the given policy ID
PUT
Updates the specified global policy
POST /dataSource/{dataSourceId}/accessManually grants write access to a user.
dataSourceId integer
The unique identifier of the data source.
The request accepts a JSON or YAML payload. See the write access manual grant payload description for parameter details.
The response returns the following JSON object. See the payload reference guide for details about the response schema.
POST /policy/globalCreates a global policy.
The example below grants write access to users with the attribute has.write and applies the global policy to all data sources.
The example below grants users write access when they are individually selected by data owners and applies the policy to data sources with columns tagged Discovered.Person Name.
The request accepts a JSON or YAML payload. See the global policy payload description for parameter details.
The response returns the global policy configuration. See the payload reference guide for details about the response schema.
DELETE /policy/global/{policyId}Deletes the specified policy.
policyId integer
The unique identifier of the policy.
The response returns the deleted global policy configuration. See the payload reference guide for details about the response schema.
GET /policy/global/{policyId}Gets the specified policy.
policyId integer
The unique identifier of the policy.
The response returns the global policy configuration. See the payload reference guide for details about the response schema.
PUT /policy/global/{policyId}Updates the specified policy.
The request accepts a JSON or YAML payload. See the global policy payload description for parameter details.
The response returns the updated global policy configuration. See the payload reference guide for details about the response schema.
Subscription API reference guide
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.
Domains API reference guide
The collections object represents a domain you've created that contains data sources and assigned permissions. Currently, the only collection type available is a domain, so collections and domains are referred to interchangeably throughout this page.
POST /collectionGET /collectionRetrieve domains created in Immuta. These results can be filtered by permission or by name.
The following table describes optional query parameters for retrieving domains.
GET /collection/{collectionId}Retrieve a domain with the given collectionId to view the data sources, description, and assigned permissions associated with the domain.
GET /collection/{collectionType}/{collectionName}Retrieve a domain with the given collectionName to view the data sources, description, and assigned permissions associated with the domain.
PUT /collection/{collectionId}Change the domain name or description. You must have the global GOVERNANCE permission to update the domain.
Path parameter
Body parameters
DELETE /collection/{collectionId}Delete a domain. The domain must have zero data sources for a user with the global GOVERNANCE permission to delete the domain.
Path parameter
Query parameter
Returns a 204 code when the domain is successfully deleted. Additional responses are provided below:
400: An invalid ID was provided.
404: The domain was not found.
POST /collection/{collectionId}/datasourcesAdd existing data sources to a domain. You must have the GOVERNANCE permission.
The request will fail if any data source IDs that have already been assigned to a domain are included in the payload.
Path parameter
Body parameter
Returns a unique identifier of the background job that adds the data sources to the domain.
GET /collection/{collectionId}/datasourcesRetrieve the data sources within a domain.
Path parameter
Query parameters
Returns a data property that contains an array of up to size data sources. Each entry in the array is a separate data source. If there are no data sources in the domain, the array will be empty.
DELETE /collection/{collectionId}/datasources/{dataSourceId}Remove data sources from a domain. To remove data sources from a domain, you must have the global CREATE_DATA_SOURCE permission.
Returns a 204 code when the data source is successfully removed from the domain. Additional responses are included below:
403: Requesting user does not have permission to remove the data source.
404: The specified collection or data source was not found.
POST /collection/{collectionId}/permissionsAssign domain permissions to a specific user. You must have the global USER_ADMIN permission to assign domain permissions to users.
Path parameter
Body parameters
GET /collection/{collectionId}/permissions/{memberType}Retrieve a list of permissions associated with the domain.
Path parameters
Query parameters
Returns a data property that contains an array of users or groups who have been assigned that permission in the domain.
GET /collection/permissions/{memberType}/{memberId}Retrieve a list of permissions for the specified user or group across all domains they are a member of.
Returns a data property that contains an array of permissions that have been assigned to the user or group in all the domains they are a member of.
DELETE /collection/{collectionId}/permissions/{permissionId}Remove a domain permission from a specific user or group. You must have the global USER_ADMIN permission to remove domain permissions from users and groups.
Returns a 204 code when the permission is successfully removed from the user. Additional responses are provided below:
400: Invalid permission
404: Collection or permission not found
DELETE /collection/{collectionId}/permissions/{memberType}/{memberId}/{permissionType}Remove a domain permission based on the permission type. You must have the global USER_ADMIN permission to remove domain permissions from users and groups.
Returns a 204 code when the permission is successfully removed. Additional responses are provided below:
400: Invalid permission
404: Collection or permission not found
The parameters for manually granting write access to a data source without using a policy are outlined in the table below.
The parameters for creating a global write policy are outlined in the table below.
The actions array specifies the policy access type and restriction level. Its child parameters are outlined in the table below.
The circumstances object specifies the conditions under which the policy applies to a data source. Its child parameters are outlined in the table below.
This section of API documentation is specific to searching for data and audit logs, managing policies and access requests, and auditing user activity.
Policies can also be created and managed using the .
: Manage and review data and subscription policies in Immuta.
: Author policies to manage write access to data sources.
: 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 by schema.
Create a new domain. You must have the global GOVERNANCE permission to create a domain. You can after creating the domain.
Returns a .
Returns a data property that contains an array of up to size . If no domains exist, the array will be empty.
Returns a .
Returns a .
Returns a with the new name or description.
Returns an array of that represent a permission in a domain assigned to a specific user. If the permission had already been assigned to the user for that domain, the response will include an error for the permissions that were not assigned to that user because the permission already existed.
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.
id string
The unique identifier of the domain.
name string
The name of the domain.
description string
The description of the domain that will be displayed for users.
createdBy integer
The unique identifier of the user who created the domain.
profile.name string
The name of the user who created the domain.
createdAt timestamp
The date and time the domain was created.
updatedAt timestamp
The date and time the domain was updated.
type string
The type of collection. Value is domain.
POST
Creates a new domain
GET
Retrieves all domains
GET
Retrieves a specific domain
GET
Retrieves a specific domain by name
PUT
Updates a domain name or description
DELETE
Deletes a domain
POST
Adds data sources to a domain
GET
Retrieves the data sources in the domain
DELETE
Deletes a data source from a domain
POST
Assigns a domain permission to a user
GET
Retrieves user permissions assigned in the domain
DELETE
Removes a domain permission from a user by the permission ID
DELETE
Removes a domain permission from a user by the user ID and permission type.
id string
The unique identifier of the domain.
Required
-
-
name string
The name of the domain.
Required
-
-
description string
The description of the domain that will be displayed for users.
Optional
-
-
type string
The type of collection.
Required
domain
domain
type string
The type of collection.
domain
offset integer
The number of items from the beginning of the response to exclude. You can combine the offset and size parameters to return a specific set of domains. For example, to return the second and third domain in the response, you would set offset=1 and size=2.
Minimum value is 0. Maximum value is the total number of domains minus size.
size integer
The number of domains to return.
Minimum value is 1. Maximum value is the total number of domains.
searchText string
The text to search for in domain names. This will return domains with a name that contains this search text.
-
withPermissions string
Only returns domains that the querying user has been granted the permission in.
Manage Policies
Audit Activity
collectionId string
The unique identifier of the domain.
collectionType string
The type of collection. The accepted value is domain.
collectionName string
The name of the domain.
collectionId string
The unique identifier of the domain.
name string
The name of the domain.
Optional
-
-
description string
The description of the domain that will be displayed for users.
Optional
-
-
collectionId string
The unique identifier of the domain.
dryRun boolean
If true, the domain will not be deleted.
collectionId string
The unique identifier of the domain.
dataSourceId integer
The unique identifier of the data source in Immuta.
Required
-
-
collectionId string
The unique identifier of the domain.
offset integer
The number of items from the beginning of the response to exclude. You can combine the offset and size parameters to return a specific set of data sources. For example, to return the second and third data source in the response, you would set offset=1 and size=2.
Minimum value is 0. Maximum value is the total number of data sources minus size.
size integer
The number of data sources to return.
Minimum value is 1. Maximum value is the total number of data sources.
collectionId string
The unique identifier of the domain from which to remove the data source.
dataSourceId integer
The unique identifier of the data source to remove.
id string
The unique identifier of the permissions object.
profileId integer
The unique identifier of the user the permission is assigned to.
groupId integer
The unique identifier of the group the permission is assigned to.
collectionId string
The unique identifier of the domain.
permission string
The permission assigned to the user. Accepted values are Manage Policies or Audit Activity.
createdAt timestamp
The date and time the permission object was created.
source string
Indicates whether the permission was assigned as a user permission or a group permission.
collectionId string
The unique identifier of the domain.
groupId integer
The unique identifier of the group the permission is assigned to.
Optional
[]
-
profileId integer
The unique identifier of the user in the identity manager.
Optional
[]
-
permission string
The domain permission assigned to the user.
Required
-
Manage Policies
Audit Activity
collectionId string
The unique identifier of the domain.
memberType string
The type of member to get a list of permissions for. Possible values include user or group.
type string
The permission to return.
Manage Policies
Audit Activity
offset integer
The number of items from the beginning of the response to exclude. You can combine the offset and size parameters to return a specific set of domain users. For example, to return the second and third domain users in the response, you would set offset=1 and size=2.
Minimum value is 0. Maximum value is the total number of domain users minus size.
size integer
The number of users to return.
Minimum value is 1. Maximum value is the total number of domain users.
searchText string
A string used to filter the results returned by the name.
-
sortField string
Specifies the field to sort the results by.
collectionId
name
profileId
sortOrder string
Specifies how to sort the results of the request.
asc
desc
memberType string
The type of member to get a list of permissions for. Possible values include user or group.
memberId string
The unique identifier of the user or group.
type string
The permission to return.
Manage Policies
Audit Activity
offset integer
The number of items from the beginning of the response to exclude. You can combine the offset and size parameters to return a specific set of domain permissions. For example, to return the second and third permission in the response, you would set offset=1 and size=2.
Minimum value is 0. Maximum value is the total number of domain permissions that user or group has minus size.
size integer
The number of permissions to return.
Minimum value is 1. Maximum value is the total number of domain permissions that user or group has.
searchText string
A string used to filter the results returned by the name.
-
sortField string
Specifies the field to sort the results by.
collectionId
name
profileId
sortOrder string
Specifies how to sort the results of the request.
asc
desc
collectionId string
The unique identifier of the domain.
permissionId string
The unique identifier of the assigned permission.
collectionId string
The unique identifier of the domain.
memberType string
The type of member to remove the permission from. Possible values include user or group.
memberId number
The unique identifier of the user or group.
permissionType string
The type of permission to delete. Accepted values are Manage Policies or Audit Activity.
profileId integer
The unique identifier of the user to whom you are granting write access.
Required
-
-
state string
The user's role on the data source.
Required
-
expert
owner
subscribed
accessGrant string
The type of access to grant the user.
Required
-
READ
WRITE
type string
The type of policy to create.
Required
-
subscription
name string
The name of the policy.
Required
-
-
template boolean
Specifies whether or not the policy should be available as a template.
Optional
false
true
false
Specifies the policy access type and restriction level. See the array description for details.
Required
-
staged boolean
When true, the policy is not active or applied to any data sources.
Required
-
true
false
This object specifies the conditions under which the policy applies to a data source. Set the value to null to enforce the policy only when it is applied by data owners. Do not include this object in your payload to apply the policy to all data sources. See the object description for additional parameters and details.
Optional
By default, the policy applies to all data sources.
-
type string
The type of policy. For write access policies, the type is subscription.
Required
-
data
subscription
accessGrant string
The type of access the user is granted.
Required
-
WRITE
description string
The description of the policy.
Optional
null
-
subscriptionType string
The restriction level of the subscription policy.
Required
-
approval: Users are granted access when approved by a specified user
automatic: Anyone is granted access
manual: Individually selected users are granted access
policy: Users with specified entitlements are granted access
operator string
Specifies how to combine the conditions of the policy.
Required
-
and
or
type string
The type of condition under which to apply the policy.
Required
-
anyTag
columnRegex
columnTags
noTags
server
tags
time
columnRegex object
This object indicates that the policy should apply to data sources with column names that match the regular expression. Its child parameters are outlined below.
Required when type is columnRegex.
-
-
columnRegex.regex string
A regular expression that matches names of columns.
Required when type is columnRegex.
-
-
columnRegex.caseInsensitive boolean
When true, the regular expression is case insensitive.
Optional
false
true
false
columnTag object
This object specifies the column tags required for the policy to apply to the data source. Child parameters are outlined below.
Required if type is columnTags.
-
-
columnTag.name string
The name of the tag.
Required if type is columnTags
-
-
columnTag.displayName string
The display name of the tag.
Optional
-
-
columnTag.hasLeafNodes boolean
When true, the tag applied has child tags.
Optional
-
-
server string
The server that contains the data sources the policy should be applied to.
Required when type is server.
-
-
startDate string
Applies the policy to data sources created on or after this startDate and before the endDate (if the endDate is specified).
Required when type is time.
-
-
endDate string
Applies the policy to data sources created on or before this endDate and after the startDate.
Optional
null
-
policyKey string
The unique name of the policy.
createdBy integer
The unique identifier of the user who created the policy.
createdByName string
The username of the user who created the policy.
createdAt string
The date the policy was created.
clonedFrom integer
The unique identifier of the policy that the new policy was cloned from.
systemGenerated boolean
Indicates whether or not the policy is system-generated.
deleted boolean
When true, the policy has been deleted.
id integer
The unique identifier of the policy.
type string
The type of policy. For write access policies, the type is subscription.
name string
The name of the policy.
template boolean
Specifies whether or not the policy is available as a template.
certification object
The certification object only applies to data policies, not write access policies.
actions array[]
Specifies the policy access type and restriction level.
actions.type string
The type of policy. For write access policies, the type is subscription.
actions.accessGrant string
The type of access the user is granted. For write access policies, actions.accessGrant is WRITE.
actions.description string
The description of the policy.
actions.allowDiscovery boolean
When true, users can still see that the data source exists in Immuta, even if they do not have the attributes and groups specified by the policy.
actions.subscriptionType string
The restriction level of the subscription policy.
actions.shareResponsibility boolean
When true, users need to meet the conditions in this policy OR another share responsibility policy that applies to the data source. This parameter is not applicable to policies with actions.subscriptionType with a value of manual.
actions.automaticSubscription boolean
When true, users will automatically be subscribed to the data source when they meet the conditions specified in the policy. This parameter is not applicable to policies with actions.subscriptionType with a value of manual.
staged boolean
When true, the policy is staged and not active on any data sources.
circumstances array[]
Specifies the conditions under which the policy applies to a data source. See the object description for child parameters.
isSubscriptionOverride boolean
When true, the user was manually granted write access by a data owner instead of being granted access by a policy on the data source.
id integer
The unique identifier of the user's subscription to the data source.
modelId integer
The unique identifier of the data source.
modelType string
The type of model the subscription policy applies to. For write policies, modelType is dataSource.
state string
The type of role the user has, such as expert, owner, or subscribed.
admin integer
The unique identifier of the user who granted write access to the data source subscriber.
denialReasoning string
If the user was denied access to the data source, this field contains the reason entered by the owner who denied access.
profile integer
The unique identifier of the user who has been granted write access.
group string
The name of the group that has been granted write access, when applicable.
policy boolean
When true, the access has been granted by a policy on the data source.
expiration string
The date the user's access expires.
acknowledgeRequired boolean
When true, the users must manually request access to the data source.
createdAt string
The date and time the user's access to the data source was granted.
updatedAt string
The date and time the user's access to the data source was updated.
accessGrant string
The type of access the user has to the data source: READ or WRITE.
approved boolean
When true, the user's access to the data source has been approved.
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
Schemas API reference guide
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.
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.
This example request gets all of the schemas with the string "medical" in their name.
Organizations API reference guide
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.
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.
The following request searches for organizations that contain Immuta in their name.
Audit API reference guide
This endpoint has been deprecated and replaced by Export UAM records.
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.
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
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.
The following request searches for all audit records.
GET /audit/{recordId}
Retrieve a specific audit record.
recordId
string The audit record ID.
Yes
hits
metadata Details regarding the returned audit record.
The following request retrieves a specific audit record.
GET /audit/apikey/activity
Queries for the recent activity using the API key.
recordId
string The audit record ID.
Yes
value
metadata regarding the recent activity.
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.
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.
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.
The following request returns the list of the current user's distinct queries.
Connection strings API reference guide
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.
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.
The following request searches across all connection strings in the handler table.
This page describes how to update policies using the Policy Handler API.
POST
/policy/handler
200
The create policy handler endpoint must be a policy handler object.
PUT
/policy/handler
200
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:
Policy API reference guide
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
POST or PUT
/policy/handler/{dataSourceId}
POST
/policy/global/applyPolicy
PUT
/policy/global/{policyId}
POST /policy/global
Create a Global Policy with a given entityType.
body
array Contains Global Policy metadata.
Yes
See the Policy Handler Objects tutorial for payload examples and details.
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.
dataSourceId
integer The ID of the data source.
Yes
jsonPolicies
array[object] An array of JSON rules objects.
Yes
id
integer The policy handler ID.
url
string The URL of the Immuta tenant.
dataSourceId
integer The ID of the data source the policy is applied to.
createdBy
integer The ID of the user who created the policy.
ca
string The certificate authority.
jsonPolicies
array[object] Policy metadata, including the policy type (visibility, masking, time, minimization, exemption, external, prerequisite, customWhere, showRowsNever, or rowOrObjectRestriction), rules, and description.
rules
string The conditions of the policy.
createdAt
timestamp The date the policy was created.
updatedAt
timestamp The date the policy was modified.
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.
payload
array Contains Global Policy and data source metadata.
Yes
policyID
integer The ID of the Global Policy.
Yes
dataSourceID
integer The ID of the data source to apply the policy to.
Yes
merged
boolean Default false.
Yes
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.
policyID
integer The ID of the Global Policy you want to update.
Yes
payload
array Contains Global Policy and metadata.
Yes
See the Policy Handler Objects tutorial for payload examples and details.
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
GET
/policy/global/{policyId}
GET
/policy/global
GET
/policy/global/appliedTo/{policyId}
GET
/policy/dataSourcePolicies/{dataSourceId}
GET
/policy/diff/{dataSourceId}
GET
/policy/handler/{dataSourceId}
POST /policy/search
Searches for specified policies.
body
array[object] Facets of the policy to search by, including the rule type, where the policy applies, exceptions, and policy circumstances.
No
type
string The type of policy to search for: data or subscription.
No
scope
string Indicates whether the policy is global or local.
No
size
integer Pages results by default; size is the number of results to return per page.
No
offset
integer Used in combination with size to fetch pages.
No
sortField
string Indicates which field to sort the policies by: name, createdBy, createdAt, state, isNotApplied, or scope.
No
sortOrder
string Indicates whether to sort policies in ascending or descending order: asc or desc.
No
searchText
string Searches text; this will filter policies by name.
No
countOnly
boolean When true, will only return the number of policies found in the search.
No
mode
string Attribute options include similarPolicies, impactedUsers, or impactedDataSources.
No
excludedPolicies
array[integer] Global Policy IDs to exclude.
No
Count
integer The number of policies found that match the search criteria.
Hits
array Policy metadata, including the name, scope, type, and data sources it applies to.
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.
policyId
integer The ID of the Global Policy.
Yes
The response returns a policy object.
This example request returns the Global Policy with the ID 1.
GET /policy/global
Find the policy with the specified entity type.
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.
No
sortField
string Indicates which field to sort the policies by: name or createdAt. Default createdAt.
No
sortOrder
string Indicates whether to sort policies in ascending or descending order: asc or desc. Default desc.
No
searchText
string Searches text; this will filter policies by name.
No
type
string The type of policy to search for: data or subscription.
No
scope
string Indicates whether the policy is global or local.
No
nameOnly
boolean When true, only returns the policy name, type, and ID.
No
templates
boolean When true, returns templates only. When false, returns non-templates only. When omitted, returns both.
No
name
string The name of the policy.
id
integer The policy ID.
type
string The type of policy: data or subscription.
hits
array Policy metadata, including the name, scope, type, and dataSources it applies to.
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.
policyId
integer The ID of the Global Policy.
Yes
count
integer The number of data sources the 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.
dataSourceId
integer The ID of the data source.
Yes
retrieveAll
boolean When false, filters out any custom domain-specific language rules.
No
excludeGlobal
boolean When true, filters out any policy actions driven by a Global Policy.
No
body
array Contains policy metadata, including the policy type, rules, exceptions, and date of creation.
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.
dataSourceId
integer The ID of the data source.
Yes
previousHandlerId
integer The ID of the previous policy.
No
currentHandlerId
integer The ID of the current policy.
No
current
array Contains policy metadata of the current policy, including the policy type, rules, exceptions, and date of creation.
previous
array Contains policy metadata of the previous policy, including the policy type, rules, exceptions, and date of creation.
hasChanges
boolean When true, indicates the policy was changed.
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.
dataSourceId
integer The ID of the data source.
Yes
hits
array Policy metadata, including the name, scope, rules, and policy type.
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.
policyId
integer The ID of the policy.
Yes
The response returns a policy object of the policy that was deleted.
The following request deletes the Global Policy with ID 6.
.
.
.
.
.
.
.
.
.
.
.