Manage Data and Subscription Policies
Understand the parameters and response schema for the policy endpoints
The policy endpoint allows you to manage and review policies in Immuta. This page outlines the endpoint and its request and response schema.
Policy workflow
Create and manage policies
POST or PUT
/policy/handler/{dataSourceId}
Create a global policy
POST /policy/global
Create a global subscription or data policy.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be a data source owner
Body parameters
type
string The type of policy. For subscription policies, this value must be subscription.
Yes
name
string The name of the policy that will be displayed in the Immuta UI.
Yes
template
boolean Specifies whether or not this policy should be available as a template.
No
actions.type
string The type of policy. Accepted value is subscription.
Yes
actions.subscriptionType
string The type of subscription policy. Accepted values are manual, policy, or guardrail.
Required when type is subscription.
actions.description
string The description of the policy.
No
actions.shareResponsibility
boolean When true the subscription policy will merge with other subscription policies on the data source with OR.
When guardrail policies are enabled, this value is set by the subscriptionType, and user-provided values for this attribute will be ignored.
No
actions.allowDiscovery
boolean When true, users can see the data source in the Immuta UI, even if they do not have the attributes and groups specified by the policy.
No
actions.accessGrant
string The type of access the user is granted. Accepted values are READ or WRITE.
No
actions.exceptions.operator
string Specifies how to combine the conditions of the policy. Accepted values are AND or OR.
No
actions.exceptions.conditions.type
string Specifies the type of entitlement to include in the exception. Accepted values are groups or authorizations.
No
actions.exceptions.conditions.type.group
string The group to allow to subscribe to the data source.
Required when actions.exceptions.conditions.type is groups.
actions.exceptions.conditions.type.authorization.auth
string The attribute key to allow to subscribe to the data source.
Required when actions.exceptions.conditions.type is authorizations.
actions.exceptions.conditions.type.authorization.value
string The attribute value to allow to subscribe to the data source.
Required when actions.exceptions.conditions.type is authorizations.
actions.automaticSubscription
boolean When true, users will be automatically subscribed to the data source without having to take action.
Yes
staged
boolean When true, the policy is not active or enforced on any data sources.
No
circumstances.type
string Specifies how to determine whether or not to apply the policy to the data source. For example, you could specify to apply the policy to data sources that have specific tags or to data sources created during a certain time period. Accepted values are columnRegex, columnTags, domains, null, server, tags, or time.
No
circumstances.columnRegex.regex
string The regular expression that identifies how column names are spelled.
Required when circumstances.type is columnRegex.
circumstances.columnRegex.caseInsensitive
boolean When true, the regex will ignore the casing of column names.
No
circumstances.server
string Specifies the server that contains the data sources the policy should be applied to.
Required when circumstances.type is server.
circumstances.startDate
string Specifies to apply policies to data sources created on or after this date and before the endDate.
Required when circumstances.type is time.
circumstances.endDate
string Specifies to apply policies to data sources created before this date and after the startDate.
No
circumstances.tag.name
string The name of the tag on the data source.
Required when circumstances.type is tags.
circumstances.tag.displayName
string The display name of the tag on the data source.
No
circumstances.tag.hasLeafNodes
boolean When true, indicates the tag on the data source has child tags.
No
circumstances.columnTag.name
string The name of the tag.
Required when circumstances.type is columnTags.
circumstances.columnTag.displayName
string The display name of the tag.
No
circumstances.columnTag.hasLeafNodes
boolean When true, indicates the tag has child tags.
No
circumstances.domains.id
string The unique identifier of the domain.
Required when circumstances.type is domains and circumstances.domains.name is not provided.
circumstances.domains.name
string The name of the domain.
Required when circumstances.type is domains and circumstances.domains.id is not provided.
circumstances.operator
string Specifies how multiple circumstances of the policy will be combined with each other. When circumstances.type is domains, this value must be AND.
Yes
type
string The type of policy. For protect data policies, this value must be data.
Yes
name
string The name of the policy that will be displayed in the Immuta UI.
Yes
template
boolean Specifies whether or not this policy should be available as a template.
No
certification.text
string The text that appears when a data owner attempts to certify a policy.
No
certification.label
string The label that appears when the policy has been certified.
No
certification.tags
array[string] Tags that impact the certification.
No
certification.recertify
boolean When true, data owners must re-certify all data sources this policy applies to.
No
actions.type
string The type of policy. Accepted values are masking, minimization, prerequisite, rowOrObjectRestriction, or time.
Yes
actions.description
string An explanation of the purpose of the policy.
No
staged
boolean When true, the policy is not enforced on any data sources.
No
circumstances.type
string Specifies how to determine whether or not to apply the policy to the data source. For example, you could specify to apply the policy to data sources that have specific tags or to data sources created during a certain time period. Accepted values are columnRegex, columnTags, domains, null, server, tags, or time.
No
circumstances.columnRegex.regex
string The regular expression that identifies how column names are spelled.
Required when circumstances.type is columnRegex.
circumstances.columnRegex.caseInsensitive
boolean When true, the regex will ignore the casing of column names.
No
circumstances.server
string Specifies the server that includes the data sources to apply the policy to.
Required when circumstances.type is server.
circumstances.startDate
string Specifies to apply policies to data sources created on or after this date and before the endDate.
Required when circumstances.type is time.
circumstances.endDate
string Specifies to apply policies to data sources created before this date and after the startDate.
No
circumstances.tag.name
string The name of the tag on the data source.
Required when circumstances.type is tags.
circumstances.tag.displayName
string The display name of the tag on the data source.
No
circumstances.tag.hasLeafNodes
boolean When true, indicates the tag on the data source has child tags.
No
circumstances.columnTag.name
string The name of the tag.
Required when circumstances.type is columnTags.
circumstances.columnTag.displayName
string The display name of the tag.
No
circumstances.columnTag.hasLeafNodes
boolean When true, indicates the tag has child tags.
No
circumstances.domains.id
string The unique identifier of the domain.
Required when circumstances.type is domains and circumstances.domains.name is not provided.
circumstances.domains.name
string The name of the domain.
Required when circumstances.type is domains and circumstances.domains.id is not provided.
circumstances.operator
string Specifies how multiple circumstances of the policy will be combined with each other. When circumstances.type is domains, this value must be AND.
Yes
Rules array
The rules array configures the type of data policy to enforce. The table below outlines its child attributes.
type
string The type of policy. Accepted values are masking, minimization, prerequisite, time, or visibility.
config.fields.name
string The name of the tag on the column that should be masked. Required when type is masking.
config.fields.displayName
string The display name of the tag on the column that should be masked.
config.fields.hasLeafNodes
boolean When true, indicates that the tag on the column to be masked has child tags.
config.maskingConfig.type
string Specifies the type of masking to apply to the data. Accepted values are Consistent Value, Format Preserving Masking, Grouping, Regular Expression, or Reversible.
config.maskingConfig.metadata.constant
string Specifies the string that will replace the value in the column. Use this attribute when config.maskingConfig.type is Consistent Value and you want to specify the constant used to replace the value.
config.maskingConfig.metadata.bucketSize
integer The bucket size to round to. Use this value when config.maskingConfig.type is Grouping and you want to mask a numeric value.
config.maskingConfig.metadata.timePrecision
string Specifies where Immuta will round the time to. Accepted values are HOUR, DAY, MONTH, QUARTER, or YEAR. Use this when config.maskingConfig.type is Grouping and you want to mask a time value.
config.maskingConfig.metadata.regex
string The regular expression that identifies the portion of the value to mask.
config.maskingConfig.metadata.replacement
string The string that will replace the portion of the value identified by the regular expression to mask.
config.percent
integer Specifies the percentage of the data to show. Required when type is minimization.
exceptions.conditions.authorization
string When actions.exceptions.conditions.type is hasTagAs, this value specifies the attribute key that will be used to match the user's attribute key-value pair against the column or data source tag.
If a user possesses an attribute with a key and value that matches any tag on the data source or column, they will see the masked data in the tagged data source or column in the clear.
exceptions.conditions.authorization.auth
string The attribute key to exempt from the data policy. Required when actions.exceptions.conditions.type is authorizations.
exceptions.conditions.authorization.value
string The attribute value to exempt from the data policy. Required when actions.exceptions.conditions.type is authorizations.
exceptions.conditions.conditionType
string When actions.exceptions.conditions.type is hasTagAs, this value specifies the type of user entitlement to match against the data source or column tag. Accepted values are attribute or group.
See the Masking policies reference guide for details about these policy exceptions.
exceptions.conditions.group.name
string The group to exempt from the data policy. Required when actions.exceptions.conditions.type is groups.
exceptions.conditions.target
string When actions.exceptions.conditions.type is hasTagAs, this value specifies whether to match the user's group or attribute to a tag on the column or data source. Accepted values are column and datasource.
exceptions.conditions.type
string Specifies the types of entitlements to exempt from the policy. Accepted values are authorizations, groups, hasTagAs, or purposes. An example payload for each of these policy exception types is provided in the section below.
See the Masking policies reference guide for details about these policy exceptions.
exceptions.conditions.value
string The purpose to exempt from the data policy. Required when actions.exceptions.conditions.type is purposes.
exceptions.operator
string Specifies the combination of entitlements the user must have to be exempt from the policy. Accepted values are AND or OR.
inclusions.conditions.authorization.auth
string The attribute key the user must have for the data policy to apply to them. Required when inclusions.conditions.type is authorizations.
inclusions.conditions.authorization.value
string The attribute value the user must have for the data policy to apply to them. Required when inclusions.conditions.type is authorizations.
inclusions.conditions.conditionType
string When actions.inclusions.conditions.type is hasTagAs, this value specifies the type of user entitlement to match against the data source or column tag to determine whether the policy applies to the user. Accepted values are attribute or group.
See the Masking policies reference guide for details about using these entitlements in policies.
inclusions.conditions.group
string The group the user must belong to for the data policy to apply to them. Required when inclusions.conditions.type is groups.
inclusions.conditions.target
string When actions.inclusions.conditions.type is hasTagAs, this value specifies whether to match the user's group or attribute to a tag on the column or data source to determine whether the policy applies to the user. Accepted values are column and datasource.
inclusions.conditions.type
string Specifies the types of entitlements the user must have for the data policy to apply to them. Accepted values are authorizations, groups, hasTagAs, or purposes.
inclusions.conditions.value
string The purpose the user must be acting under for the data policy to apply to them. Required when inclusions.conditions.type is purposes.
inclusions.operator
string Specifies the combination of entitlements the user must have for the policy to apply to them. Accepted values are AND or OR.
type
string The type of policy. For reveal data policies, this value must be data.
Yes
name
string The name of the policy that will be displayed in the Immuta UI.
Yes
template
boolean Specifies whether or not this policy should be available as a template.
No
actions.type
string The type of policy. This value must be exception for reveal policies.
Yes
actions.description
string An explanation of the purpose of the policy.
No
staged
boolean When true, the policy is not enforced on any data sources.
No
circumstances.type
string Specifies how to determine whether or not to apply the policy to the data source. For example, you could specify to apply the policy to data sources that have specific tags or to data sources created during a certain time period. Accepted values are columnRegex, columnTags, domains, null, server, tags, or time.
No
circumstances.columnRegex.regex
string The regular expression that identifies how column names are spelled.
Required when circumstances.type is columnRegex.
circumstances.columnRegex.caseInsensitive
boolean When true, the regex will ignore the casing of column names.
No
circumstances.server
string Specifies the server that includes the data sources to apply the policy to.
Required when circumstances.type is server.
circumstances.startDate
string Specifies to apply policies to data sources created on or after this date and before the endDate.
Required when circumstances.type is time.
circumstances.endDate
string Specifies to apply policies to data sources created before this date and after the startDate.
No
circumstances.tag.name
string The name of the tag on the data source.
Required when circumstances.type is tags.
circumstances.tag.displayName
string The display name of the tag on the data source.
No
circumstances.tag.hasLeafNodes
boolean When true, indicates the tag on the data source has child tags.
No
circumstances.columnTag.name
string The name of the tag.
Required when circumstances.type is columnTags.
circumstances.columnTag.displayName
string The display name of the tag.
No
circumstances.columnTag.hasLeafNodes
boolean When true, indicates the tag has child tags.
No
circumstances.domains.id
string The unique identifier of the domain.
Required when circumstances.type is domains and circumstances.domains.name is not provided.
circumstances.domains.name
string The name of the domain.
Required when circumstances.type is domains and circumstances.domains.id is not provided.
circumstances.operator
string Specifies how multiple circumstances of the policy will be combined with each other. When circumstances.type is domains, this value must be AND.
Yes
Rules array
The rules array configures the type of reveal data policy to enforce. The table below outlines its child attributes. Reveal policies are only supported for the exception type.
type
string The type of policy. Accepted value is exception.
config.fields.name
string The name of the tag on the column that should be revealed. Required when type is exception.
config.fields.displayName
string The display name of the tag on the column that should be revealed.
config.fields.hasLeafNodes
boolean When true, indicates that the tag on the column to be revealed has child tags.
exceptions.conditions.authorization.auth
string The attribute key the user must have for the reveal policy to apply to them. Required when exceptions.conditions.type is authorizations.
exceptions.conditions.authorization.value
string The attribute value the user must have for the reveal policy to apply to them. Required when exceptions.conditions.type is authorizations.
exceptions.conditions.conditionType
string When actions.exceptions.conditions.type is hasTagAs, this value specifies the type of user entitlement to match against the data source or column tag to determine whether the reveal policy applies to the user. Accepted values are attribute or group.
See the Masking policies reference guide for details about using these entitlements in policies.
exceptions.conditions.group
string The group the user must belong to for the reveal policy to apply to them. Required when exceptions.conditions.type is groups.
exceptions.conditions.target
string When actions.exceptions.conditions.type is hasTagAs, this value specifies whether to match the user's group or attribute to a tag on the column or data source to determine whether the reveal policy applies to the user. Accepted values are column and datasource.
exceptions.conditions.type
string Specifies the types of entitlements the user must have for the reveal policy to apply to them. Accepted values are authorizations, groups, or hasTagAs.
exceptions.operator
string Specifies the combination of entitlements the user must have for the reveal policy to apply to them. Accepted values are AND or OR.
Request example
This example request creates a global policy (saved in the example-payload.json file) in the Immuta tenant.
Request payload examples
This sample payload creates the following subscription policy:
Automatically grant users access when user is a member of group
HRon data sources taggedEmployee.
This sample payload creates the following masking policy:
Mask data tagged
PIIfor everyone on data sources with columns taggedPII.
Attribute exception examples
This sample payload creates the following masking policy:
Mask columns tagged
PIIby making NULL for everyone except when user possesses attributeDepartment:HR.
This sample payload creates the following masking policy:
Mask columns tagged
PIIby making NULL for everyone except when user possesses an attribute with keyEmployeeand value that matches any column tag.
Group exception examples
This sample payload creates the following masking policy:
Mask by making NULL columns tagged
PIIfor everyone except when user is a member of groupHR.
This sample payload creates the following masking policy:
Mask columns tagged
PIIby making NULL for everyone except when user is a member of a group with name that matches any data source tag.
Purpose exception example
This sample payload creates the following masking policy:
Mask columns tagged
PIIby making NULL for everyone except when user is acting under purposeEmployee Retention.
This sample payload creates the following row-access policy:
Only show rows where user is a member of a group that matches the value in column tagged
Departmentfor everyone on data sources with columns taggedDepartment.
This sample payload creates the following reveal policy:
Reveal columns tagged
Marketingon data sources with columns tagged
Response example
Create or update a policy for a specific data source
POST or PUT /policy/handler/{dataSourceId}
Create (POST) or update (PUT) a policy for the specified data source.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be a data source owner
Path parameter
dataSourceId
integer The ID of the data source.
Yes
Body parameter
jsonPolicies
array[object] An array of JSON rules objects.
Yes
Response schema
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, prerequisite, customWhere, showRowsNever, or rowOrObjectRestriction), rules, and description.
rules
object The conditions of the policy.
createdAt
timestamp The date the policy was created.
updatedAt
timestamp The date the policy was modified.
Request example
This example request applies the policy specified in the payload to the data source with the ID 2.
Request payload example
Response example
Apply a global policy to a data source
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.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be a data source owner
Body parameters
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
Response schema
None. When successful, no message will display.
Request example
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.
Update a global policy
PUT /policy/global/{policyId}
Update the specified policy.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be the policy creator
Path parameters
policyId
integer The ID of the global policy you want to update.
Yes
Body parameters
See the Create a global policy section for payload details.
Response schema
When successful, the response returns the body of the request payload.
Request example
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.
Response example
Review policies
GET
/policy/global/appliedTo/{policyId}
GET
/policy/dataSourcePolicies/{dataSourceId}
Search for policies
POST /policy/search
Searches for specified policies.
Body parameters
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
Response schema
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.
Request example
This example request searches for a global policy that contains the text mask in Immuta.
Response example
Find policies by policy ID
GET /policy/global/{policyId}
Find the policy with the specified ID.
Path parameter
policyId
integer The ID of the global policy.
Yes
Response schema
The response returns a policy object. See the Create a global policy section for descriptions.
Request example
This example request returns the global policy with the ID 1.
Response example
Find policies by entity type
GET /policy/global
Find the policy with the specified entity type.
Query parameters
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
Response schema
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.
Request example
This example request returns the name, type, and ID of all policies.
Response example
Find the number of data sources a specified policy applies to
GET /policy/global/appliedTo/{policyId}
Find the number of data sources the specified policy applies to.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be a data source owner
Path parameter
policyId
integer The ID of the global policy.
Yes
Response schema
count
integer The number of data sources the policy applies to.
Request example
This example request returns the number of data sources the global policy with the ID 6 applies to.
Response example
Get the policy information for a specific data source
GET /policy/dataSourcePolicies/{dataSourceId}
Get the policy information for the specified data source.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be a data source owner
Path parameter
dataSourceId
integer The ID of the data source.
Yes
Query parameters
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
Response schema
type
string The type of policy.
rules
array The rules for the data policy enforcement.
exceptions
array The entitlements to exempt from the policy.
createdAt
timestamp The time the policy was created.
createdBy
integer The ID of the user who created the policy.
Request example
This example request returns the information of policies applied to the data source with the ID 2.
Response example
Get the differences between two policy versions
GET /policy/diff/{dataSourceId}
Get the differences between two policy handler versions.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be a data source owner
Path parameter
dataSourceId
integer The ID of the data source.
Yes
Query parameters
previousHandlerId
integer The ID of the previous policy.
No
currentHandlerId
integer The ID of the current policy.
No
Response schema
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.
Request example
This example request returns the information of policies applied to the data source with the ID 3.
Response example
Get the policy handler metadata for a specific data source
GET /policy/handler/{dataSourceId}
Get the policy handler metadata for a specific data source.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be a data source owner
Path parameter
dataSourceId
integer The ID of the data source.
Yes
Response schema
hits
array Policy metadata, including the name, scope, rules, and policy type.
Request example
This example request returns the policy handler metadata for policies applied to the data source with the ID 1.
Response example
Delete a global policy
DELETE /policy/global/{policyId}
Delete the specified global policy.
Requirement: GOVERNANCE permission, domain-specific Manage Policies permission, or be the policy creator
Path parameter
policyId
integer The ID of the policy.
Yes
Response schema
The response returns a policy object of the policy that was deleted. See the Create a global policy section for descriptions.
Request example
The following request deletes the global policy with ID 6.
Response example
Last updated
Was this helpful?