# Policy Handler Objects

This page describes how to update policies using the Policy Handler API.

## Create policy handler

| Method | Path              | Successful Status Code |
| ------ | ----------------- | ---------------------- |
| POST   | `/policy/handler` | 200                    |

### Request parameters

The create policy handler endpoint must be a [policy handler object](#policy-handler-object).

## Update policy handler

| Method | Path              | Successful Status Code |
| ------ | ----------------- | ---------------------- |
| PUT    | `/policy/handler` | 200                    |

### Request parameters

The update policy handler endpoint must be a [policy handler object](#policy-handler-object).

## 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](#defining-policy-rules)

## Defining policy rules

The `jsonRules` array contains rules objects. The following types of policy rules are supported:

* [Prerequisite](#prerequisite-policy-rule-type)
* [Visibility](#visibility-policy-rule-type)
* [Masking](#masking-policy-rule-type)
* [Minimization](#minimization-rule-type)
* [Time-based](#time-based-rule-type)

Not all combination of policy rules are valid. The examples below are supported policy rule combinations:

* Prerequisite, Visibility, Masking
* Prerequisite, Masking, Minimization

### Prerequisite policy rule type

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](#purpose-policy-condition)

**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`.

```json
{
    "type": "prerequisite",
    "operator": "or",
    "conditions": [{
        "type": "purposes",
        "value": "Purpose Name"
    }]
}
```

### Visibility policy rule type

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](#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.*

```json
{
    "type": "groups",
    "field": "organization",
    "group": {
        "iam": "active_directory"
    }
}
```

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`.

```json
{
    "type": "visibility",
    "operator": "and",
    "conditions": [{
        "type": "authorizations",
        "field": "department",
        "authorization": {
            "auth": "accesses",
            "iam": "active_directory"
        }
    }, {
        "type": "groups",
        "field": "organization",
        "group": {
            "iam": "active_directory"
        }
    }]
}
```

### Masking policy rule type

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](#policy-conditions)

*Note: When adding conditions to a masking policy rule, the `field` will be left blank, and the condition `value` should be populated.*

```json
{
    "type": "groups",
    "group": {
        "name": "users",
        "iam": "active_directory"
    }
```

When using a masking rule, there is an additional field that needs to be sent in the [update data source request](#update-policy-handler) 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](#masking-configuration-metadata)

#### 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**:

```json
{
    "policyHandler": {
        "maskingConfiguration": [{
            "type": "Consistent Value",
            "name": "age",
            "metadata": {
                "constant": "REDACTED"
            }
        }]
    }
}
```

**Example**:

In this example, the fields `email` and `location` will be masked unless the user belongs to the group `admins`.

```json
{
    "type":"masking",
    "fields": ["email", "location"],
    "operator":"or",
    "conditions":[{
        "type":"groups",
        "group":{
            "name":"admins",
            "iam":"active_directory"
        }
    }]
}
```

### Minimization rule type

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](#policy-conditions)

*Note: When adding conditions to a minimization policy rule the `field` will be left blank.*

```json
{
    "type": "groups",
    "group": {
        "name": "users",
        "iam": "active_directory"
    }
```

When using a minimization rule, there is an additional field that needs to be sent in the [update data source request](#update-policy-handler) 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.

```json
{
    "type": "additional",
    "name": "minimization",
    "operator": "or",
    "conditions": {
        "type":"groups",
        "group":{
            "name":"admins",
            "iam":"active_directory"
        }
    }
}
```

**Example data source update (partial)**:

```json
{
    "policyHandler": {
        "additionalFilters": {
            "minimization": {
                "percent": 50,
                "hashPhrase": "name"
            }
        }
    }
}
```

### Time-based rule type

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](#policy-conditions)

*Note: When adding conditions to a time based policy rule the `field` will be left blank.*

```json
{
    "type": "groups",
    "group": {
        "name": "users",
        "iam": "active_directory"
    }
```

When using a time based rule, there is an additional field that needs to be sent in the [update data source request](#update-policy-handler) 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.

```json
{
    "type": "additional",
    "name": "time",
    "operator": "or",
    "conditions": {
        "type":"groups",
        "group":{
            "name":"admins",
            "iam":"active_directory"
        }
    }
}
```

**Example data source update (partial)**:

```json
{
    "policyHandler": {
        "additionalFilters": {
            "time": 14400
        }
    }
}
```

## Policy conditions

There are three types of policy conditions:

1. [Groups](#group-policy-condition)
2. [Attributes](#attribute-policy-condition)
3. [Purposes](#purpose-policy-condition)

### Group policy condition

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](#group-object)
* `field` (*string*): Data field to match group name against when checking policy.
  * **Example:** `"department"`

**Example**:

```json
{
    "type": "groups",
    "group": {
        "name": "users",
        "iam": "active_directory"
    },
    "field": "department"
}
```

#### Group object

* `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"`

### Attribute policy condition

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](#group-object)
* `field` (*string*): Data field to match attribute value against when checking policy.
  * **Example:** `"department"`

**Example**:

```json
{
    "type": "authorizations",
    "authorization": {
        "auth": "accesses",
        "value": "PII",
        "iam": "active_directory"
    },
    "field": "department"
}
```

### Attribute object

* `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"`

### Purpose policy condition

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**:

```json
{
    "type": "purposes",
    "value": "Purpose",
    "field": "department"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/2024.2/developer-guides/api-intro/immuta-v1-api/manage-data-access/policy-handler.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.