# Create a Data Policy ## POST `/api/v2/policy` **Required Immuta permission**: `GOVERNANCE` {% tabs %} {% tab title="Simple masking policy" %} This simple masking policy masks all columns with no tags using a hash function. ```yaml name: Hashing policyKey: data mask hashing type: data actions: - rules: - type: Masking config: fields: - type: noTags maskingConfig: type: Hash circumstances: - type: noTags ``` {% endtab %} {% tab title="Complex masking policy" %} This complex masking policy masks columns with specific tags using a constant value, but only if the user does not have certain attributes. If the user has the `auth` attribute set to `SOMETHING_ELSE` or `auth1` set to `super secret`, the masking policy will not be applied. ```yaml name: Mask with Constant policyKey: data mask constant type: data actions: - rules: - type: Masking exceptions: operator: any attributes: - name: auth value: SOMETHING_ELSE - name: auth1 value: super secret config: fields: - type: columnTags columnTag: Discovered.Country - type: columnTags columnTag: Discovered.Passport maskingConfig: type: Constant constant: REDACTED circumstanceOperator: any circumstances: - type: columnTags columnTag: Discovered.Country - type: columnTags columnTag: Discovered.Passport ``` {% endtab %} {% endtabs %}
Other policy type examples **Masking policies** **Conditional masking** ```yaml name: Conditional Masking policyKey: data conditional masking type: data actions: - rules: - type: Masking config: fields: - type: columnTags columnTag: Discovered.Passport conditionalPredicate: "@columnTagged('Discovered.Country') = 'USA'" maskingConfig: type: Hash circumstanceOperator: all circumstances: - type: columnTags columnTag: Discovered.Passport - type: columnTags columnTag: Discovered.Country ``` **Conditional masking with an otherwise clause** ```yaml name: Conditional policyKey: data mask otherwise type: data actions: - rules: - type: Masking config: fields: - type: columnTags columnTag: Discovered.Country maskingConfig: type: "Null" inclusions: groups: - Employee - type: Masking exceptions: purposes: - Re-identification Prohibited config: fields: - type: columnTags columnTag: Discovered.Country maskingConfig: type: Hash circumstances: - type: columnTags columnTag: Discovered.Country ``` **Format preserving masking** {% hint style="info" %} **Support limitation**: This policy is only supported in Snowflake integrations. {% endhint %} ```yaml name: Format Preserving Masking policyKey: data mask fpe type: data actions: - rules: - type: Masking config: fields: - type: columnTags columnTag: Discovered maskingConfig: type: Format Preserving Masking circumstances: - type: columnTags columnTag: Discovered ``` **Make null with column regex** ```yaml name: Null using column regex policyKey: data mask null type: data actions: - rules: - type: Masking config: fields: - type: columnRegex regex: ssn caseInsensitive: true maskingConfig: type: Null circumstances: - type: columnRegex regex: ssn caseInsensitive: true ``` **Randomized response** {% hint style="info" %} **Support limitation**: This policy is only supported in Snowflake integrations. {% endhint %} ```yaml name: Random Categorical policyKey: data mask random response type: data actions: - rules: - type: Masking config: fields: - type: allColumns maskingConfig: type: Randomized Response replacementRatePercent: 10 ``` **Randomized response with a standard deviation** {% hint style="info" %} **Support limitation**: This policy is only supported in Snowflake integrations. {% endhint %} **Sample data is processed during computation of randomized response policies** When a randomized response policy is applied to a data source, the columns targeted by the policy are queried under a fingerprinting process. To enforce the policy, Immuta generates and stores predicates and a list of allowed replacement values that may contain data that is subject to regulatory constraints (such as GDPR or HIPAA) in Immuta's metadata database. The location of the metadata database depends on your deployment: * Self-managed Immuta deployment: The metadata database is located in the server where you have your external metadata database deployed. * SaaS Immuta deployment: The metadata database is located in the AWS global segment you have chosen to deploy Immuta. To ensure this process does not violate your organization's data localization regulations, you need to first activate this masking policy type before you can use it in your Immuta tenant. To enable randomized response for your account, see the [randomized response section on the app settings how-to guide](https://documentation.immuta.com/SaaS/configuration/application-configuration/how-to-guides/config-builder-guide#randomized-response). ```yaml name: Random Numeric policyKey: data mask random response specifying stddev type: data actions: - rules: - type: Masking config: fields: - type: allColumns maskingConfig: type: Randomized Response stddev: 2 clip: false ``` **Using a regex** ```yaml name: Regex policyKey: data mask regex type: data actions: - rules: - type: Masking config: fields: - type: columnTags columnTag: Discovered.Entity.Postal Code maskingConfig: type: Regular Expression regex: "(\\d{4})(\\d)" replacement: "$1X" caseInsensitive: true global: true circumstances: - type: columnTags columnTag: Discovered.Entity.Postal Code ``` **With reversibility** {% hint style="info" %} **Support limitation**: This policy is only supported in Snowflake integrations. {% endhint %} ```yaml name: Mask using Reversible policyKey: data mask reversible type: data actions: - rules: - type: Masking config: fields: - type: columnTags columnTag: Discovered.Entity.Social Security Number maskingConfig: type: Reversible exceptions: groups: - founders circumstances: - type: columnTags columnTag: Discovered.Entity.Social Security Number ``` **Using date rounding** ```yaml name: RoundingDate policyKey: data mask rounding by date type: data actions: - rules: - type: Masking config: fields: - type: columnTags columnTag: Discovered.Entity.Date maskingConfig: type: Grouping timePrecision: MONTH circumstances: - type: columnTags columnTag: Discovered.Entity.Date ``` **Using rounding with fingerprint** {% hint style="info" %} **Support limitation**: This policy is only supported in Snowflake integrations. {% endhint %} ```yaml name: RoundingFingerprint policyKey: data mask round using fingerprint type: data actions: - rules: - type: Masking config: fields: - type: columnTags columnTag: Discovered.Entity.Date maskingConfig: type: Grouping circumstances: - type: columnTags columnTag: Discovered.Entity.Date ``` **Using numeric rounding** ```yaml name: RoundingNumeric policyKey: data mask round numeric type: data actions: - rules: - type: Masking config: fields: - type: columnTags columnTag: Discovered.Entity.Date maskingConfig: type: Grouping bucketSize: 10 circumstances: - type: columnTags columnTag: Discovered.Entity.Date ``` **Minimization** ```yaml name: Minimize policyKey: data minimize type: data actions: - rules: - type: Minimization config: percent: 15 circumstances: - type: time startDate: '2020-12-01T16:23:54.734Z' endDate: '2020-12-31T16:23:54.745Z' ``` **Purpose restrictions** ```yaml name: Purpose policyKey: data purpose restriction type: data actions: - rules: - type: Purpose Restriction config: operator: any purposes: - "" ``` **Row-level** **By time** ```yaml name: Row Level By Time policyKey: data row-level type: data actions: - rules: - type: Time Restriction config: isOlderOrNewer: newer time: 2592000 circumstances: - type: tags tag: Discovered.PCI ``` **Where user** ```yaml name: Row Level Where User policyKey: data where user type: data actions: - rules: - type: Row Restriction By User Entitlements config: operator: all matches: type: Group tag: Discovered.Entity circumstanceOperator: any circumstances: - type: columnTags columnTag: Discovered.Entity ``` **Custom where clause** ```yaml name: Row Level Where policyKey: data custom where type: data actions: - rules: - type: Row Restriction by Custom Where Clause config: predicate: "@columnTagged('Discovered.Country') in ('USA', 'CANADA', 'MEXICO')" circumstances: - type: tags tag: Discovered.Country ```
## Path parameters | Parameter | Description | Required or optional | Default value | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------- | | **dryRun** `boolean` | If `true`, no updates will actually be made. | Optional | `false` | | **reCertify** `boolean` | If `true` (and if the certification has changed), someone will need to re-certify this policy on all impacted data sources. | Optional | `false` | ## Body parameters The body of the request contains the details of the policy you want to create. The following table describes the attributes you can include in the body. | Attribute | Description | Required or optional | Default value | Accepted values | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------- | ------------- | --------------------------------------------------------------------- | | **policyKey** `string` | A key/name to uniquely identify this policy. | Required | - | - | | **name** `string` | The name of the policy that will be displayed in the Immuta UI. | Required | - | - | | **type** `string` | The type of policy. | Required | - | | | [**actions**](#actions-array) `array` | The actual rules for this policy. | Required | - | - | | [**circumstances**](#circumstances-array) `array` | When and where the policy should get applied. | Optional | - | - | | **circumstanceOperator** `string` | Specifies whether `all` of the circumstances must be met for the policy to be applied (AND), or just `any` of them (OR). | Optional | `any` | | | **staged** `boolean` | If `true`, this global policy is in a staged status. | Optional | `false` | | | [**certification**](#certification-object) `object` | Certification information for the global policy. | Optional | - | - | ### `actions` array The `actions` array contains one or more `rules` arrays that describe the rules of the policy. Each `rules` array can have its own configuration and exceptions. | Attribute | Description | Required or optional | Accepted values | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **rules** `array` | Details about the rules of the policy. | Required | - | | rules.**type** `string` | The type of data policy. | Required | | | [rules.**config**](#config-object) `object` | Details about the configuration of the policy. | Required | - | | rules.**inclusions** `object` | The specific users this policy is meant to affect. If you use **inclusions**, you must add a second **rules** array for the other users. [See the example](#other-policy-type-examples). | Optional | - | | rules.inclusions.**groups** `array[string]` | Group names. Users in these groups will be affected by the rules in this **rules** array. | Required for `rules.inclusions` | - | | [rules.**exceptions** ](#exceptions-object)`object` | These are the users the policy is not meant to target. | Optional | - | #### `config` object The `config` object contains the details of the policy configuration. This includes the fields the policy will be applied to and the masking configuration. | Attribute | Description | Required or optional | Accepted values | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [**fields**](#fields-array) `array` | Details about the fields where the policy should be applied. | Required | - | | [**maskingConfig**](#maskingconfig-object) `object` | The details of the masking policy. | Required if **rules.type** is `Masking` | - | | **conditionalPredicate** `string` | [A where clause](https://documentation.immuta.com/SaaS/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/custom-where-clause-functions) to dictate where the policy is applied. | Optional | - | | **operator** `string` | Specifies whether `all` of the circumstances must be met for the policy to be applied (AND), or just `any` of them (OR). | Optional | `any` | | **purposes** `array[string]` | Purpose names. Restriction to the data will be applied to everyone except users acting under these purposes. | Required if **rules.type** is `Purpose Restriction` | - | | **percent** `integer` | Specifies the percentage of the data to show. | Required if **rules.type** is `Minimization` | - | | **isOlderOrNewer** `string` | Specifies if the policy should be applied to columns `older` or `newer` than the provided time. | Required if **rules.type** is `Time Restriction` | | | **time** `integer` | The time (in seconds) that the row must be `older` or `newer` than to be visible. | Required if **rules.type** is `Time Restriction` | - | | **predicate** `string` | [A where clause](https://documentation.immuta.com/SaaS/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/custom-where-clause-functions) to dictate what rows are visible. | Required if **rules.type** is `Row Restriction by Custom Where Clause` | - | | **matches** `object` | The user entitlements that must match the value in the specified column for the row to show. | Required if **rules.type** is `Row Restriction By User Entitlements` | - | | matches.**type** `string` | The type of user entitlements to base the policy on. | Required if **rules.type** is `Row Restriction By User Entitlements` | | | matches.**tag** `string` | The tag of the column that's data must match the user's entitlement. | Required if **rules.type** is `Row Restriction By User Entitlements` | - | #### `fields` array The `fields` array specifies which columns the policy will be applied to. You can specify columns by tags, regex, or all columns. | Attribute | Description | Required or optional | Accepted values | | ----------------------------- | -------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **type** `string` | The type of Immuta source to build the policy off of. | Required | | | **columnTag** `string` | The column tag to determine which column the policy is applied to. | Required if **type** is `columnTags` | - | | **regex** `string` | The regex to match against column names and apply the policy when found. | Required if **type** is `columnRegex` | - | | **caseInsensitive** `boolean` | If `true`, the regex is case insensitive. Use with `columnRegex` **type**. | Optional | | #### `maskingConfig` object The `maskingConfig` object contains the details of the masking policy. You can specify the type of masking, the constant value to use, or a regular expression to match against. | Attribute | Description | Required or optional | Accepted values | | ----------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **type** `string` | The type of masking policy to apply. | Required if **rules.type** is `Masking` | | | **constant** `string` | Specifies the string that will replace the value in the column. | Required if **type** is `Constant` | - | | **regex** `string` | The regular expression that identifies the portion of the value to mask. | Required if **type** is `Regular Expression` | - | | **replacement** `string` | The string that will replace the portion of the value identified by the regular expression to mask. | Required if **type** is `Regular Expression` | - | | **caseInsensitive** `boolean` | If `true`, the regex is case insensitive. Use with `Regular Expression` **type**. | Optional | | | **timePrecision** `string` | Specifies where Immuta will round the time to. | Requires **timePrecision** or **bucketSize** if **type** is `Grouping` | | | **bucketSize** `integer` | The bucket size to round to. | Requires **timePrecision** or **bucketSize** if **type** is `Grouping` | - | #### `exceptions` object The `exceptions` object specifies the users that will not be affected by the policy. You can specify exceptions based on purposes or attributes. | Attribute | Description | Required or optional | Accepted values | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------------------------- | | **operator** `string` | Specifies whether `all` of the circumstances must be met for the policy to be applied (AND), or just `any` of them (OR). | Optional | | | **purposes** `array[string]` | Purpose names. Users acting under these purposes will not be affected by this policy. | Requires either **purposes** or **attributes** | - | | **attributes** `array[object]` | Attribute names and values. Users with these attributes will not be affected by this policy. | Requires either **purposes** or **attributes** | - | | attributes.**name** `string` | An attribute name. | Required if **attributes** is used | - | | attributes.**value** `string` | An attribute value. | Required if **attributes** is used | - | ### `circumstances` array The `circumstances` array dictates what data sources the policy will be applied to. 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. | Attribute | Description | Required or optional | Default value | Accepted values | | ----------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **type** `string` | Specifies how to determine whether or not to apply the policy to the data source. | Optional | Defaults to all data sources | | | **tag** `string` | The tag to dictate when the policy is applied. | Required if **type** is `tags` | - | - | | **columnTag** `string` | The column tag to dictate when the policy is applied. | Required if **type** is `columnTags` | - | - | | **regex** `string` | The regex to match against column names and apply the policy when found. | Required if **type** is `columnRegex` | - | - | | **caseInsensitive** `boolean` | If `true`, the regex is case insensitive. Use with `columnRegex` **type**. | Optional | - | | | **server** `string` | Specifies the server that contains the data sources the policy should be applied to. | Required if **type** is `server` | - | - | | **startDate** `string` | Specifies to apply policies to data sources created on or after this date and before the **endDate**. | Required if **type** is `time` | - | - | | **endDate** `string` | Specifies to apply policies to data sources created before this date and after the **startDate**. | Optional | - | - | | **domains** `array[object]` | Specifies to apply policies to data sources in the listed domains. | Required if **type** is `domains` | - | - | | domains.**id** `string` | The unique ID of the domain. | Requires either **domains.id** or **domains.name** if **type** is `domains` | - | - | | domains.**name** `string` | The name of the domain. | Requires either **domains.id** or **domains.name** if **type** is `domains` | - | - | ### `certification` object The `certification` object contains the details of the certification for the policy. | Attribute | Description | Required or optional | Default value | Accepted values | | ------------------------ | --------------------------------------------------------------------------------- | -------------------- | ------------- | -------------------------------------------------------------- | | **text** `string` | The text that appears when a data owner attempts to certify a policy. | Required | - | - | | **label** `string` | The label that appears when the policy has been certified. | Required | - | - | | **tags** `array[string]` | Tags that impact the certification. | Optional | - | - | | **recertify** `boolean` | When `true`, data owners must re-certify all data sources this policy applies to. | Optional | `false` | |