Data and Subscription Policies
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.
Policy workflow
Create and manage policies
POST
/policy/global
POST or PUT
/policy/handler/{dataSourceId}
POST
/policy/global/applyPolicy
PUT
/policy/global/{policyId}
Create a global policy with a specified entity type
POST
/policy/global
Create a Global Policy with a given entityType
.
Query parameters
body
array
Contains Global Policy metadata.
Yes
Payload parameters
See the Policy Handler Objects tutorial for payload examples and details.
Response parameters
When successful, the response returns the body of the request payload.
Request example
This example request creates a Global Policy (saved in the example-payload.json
file) in the Immuta tenant.
Request payload example
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.
Query parameters
dataSourceId
integer
The ID of the data source.
Yes
jsonPolicies
array[object]
An array of JSON rules objects.
Yes
Response parameters
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.
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.
Query parameters
payload
array
Contains Global Policy and data source metadata.
Yes
Payload 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 parameters
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.
Query parameters
policyID
integer
The ID of the Global Policy you want to update.
Yes
payload
array
Contains Global Policy and metadata.
Yes
Payload parameters
See the Policy Handler Objects tutorial for payload examples and details.
Response parameters
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
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}
Search for policies
POST
/policy/search
Searches for specified policies.
Query 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 parameters
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.
Query parameters
policyId
integer
The ID of the Global Policy.
Yes
Response parameters
The response returns a policy object.
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 parameters
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.