# Manage 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.

{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}

## Policy workflow

1. [Create and manage policies](#create-and-manage-policies).
2. [Search for, review, and compare policies](#review-policies).
3. [Delete Global Policies](#delete-a-global-policy).

## Create and manage policies

| Method      | Path                             | Purpose                                                                                                                        |
| ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| POST        | `/policy/global`                 | [Create a Global Policy with a given `entityType`](#create-a-global-policy-with-a-specified-entity-type).                      |
| POST or PUT | `/policy/handler/{dataSourceId}` | [Create (POST) or update (PUT) a policy for the specified data source](#create-or-update-a-policy-for-a-specific-data-source). |
| POST        | `/policy/global/applyPolicy`     | [Apply a Global Policy to a data source](#apply-a-global-policy-to-a-data-source).                                             |
| PUT         | `/policy/global/{policyId}`      | [Update the specified Global Policy](#update-a-global-policy).                                                                 |

### Create a global policy with a specified entity type

<mark style="color:green;">`POST`</mark> `/policy/global`

Create a Global Policy with a given `entityType`.

#### Query parameters

| Attribute | Description                              | Required |
| --------- | ---------------------------------------- | -------- |
| body      | `array` Contains Global Policy metadata. | **Yes**  |

#### Payload parameters

See the [Policy Handler Objects tutorial](https://documentation.immuta.com/2024.3/developer-guides/api-intro/immuta-v1-api/manage-data-access/policy-handler) 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.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/policy/global
```

**Request payload example**

```json
{
  "type": "data",
  "template": false,
  "ownerRestrictions": null,
  "actions": [{
    "type": "masking",
    "rules": [{
      "type": "masking",
      "exceptions": null,
      "config": {
        "fields": [{
          "name": "Discovered.Passport",
          "displayName": "Discovered > Passport",
          "hasLeafNodes": false,
          "source": "curated"
        }],
        "maskingConfig": {
          "type": "Consistent Value",
          "metadata": {}
        }
      }
    }],
    "description": ""
  }],
  "circumstances": [{
    "operator": "or",
    "type": "columnTags",
    "columnTag": {
      "name": "Discovered.Passport",
      "displayName": "Discovered > Passport",
      "hasLeafNodes": false,
      "source": "curated"
    }
  }],
  "name": "Mask Passports",
  "certification": {
    "text": "This certifies that all columns containing passports in this data source have been tagged appropriately.",
    "label": "Certified",
    "tags": [],
    "recertify": true
  },
  "staged": false
}
```

#### Response example

```json
{
  "id": 8,
  "policyKey": "Mask Passports",
  "name": "Mask Passports",
  "type": "data",
  "template": false,
  "staged": false,
  "systemGenerated": false,
  "deleted": false,
  "certification": {
    "tags": [],
    "text": "This certifies that all columns containing passports in this data source have been tagged appropriately.",
    "label": "Certified",
    "recertify": true
  },
  "actions": [{
    "type": "masking",
    "rules": [{
      "type": "masking",
      "config": {
        "fields": [{
          "name": "Discovered.Passport",
          "source": "curated",
          "hasLeafNodes": false
        }],
        "maskingConfig": {
          "type": "Consistent Value",
          "metadata": {}
        }
      },
      "exceptions": null
    }],
    "description": null
  }],
  "circumstances": [{
    "type": "columnTags",
    "operator": "or",
    "columnTag": {
      "name": "Discovered.Passport",
      "hasLeafNodes": false
    }
  }],
  "metadata": null,
  "clonedFrom": null,
  "createdBy": 2,
  "createdAt": "2021-09-21T18:35:48.615Z",
  "updatedAt": "2021-09-21T18:35:48.615Z",
  "createdByName": "Katie",
  "ownerRestrictions": null
}
```

### Create or update a policy for a specific data source

<mark style="color:green;">`POST`</mark> or <mark style="color:green;">`PUT`</mark> `/policy/handler/{dataSourceId}`

Create (POST) or update (PUT) a policy for the specified data source.

#### Query parameters

| Attribute    | Description                                     | Required |
| ------------ | ----------------------------------------------- | -------- |
| dataSourceId | `integer` The ID of the data source.            | **Yes**  |
| jsonPolicies | `array[object]` An array of JSON rules objects. | **Yes**  |

#### Response parameters

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

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/policy/handler/2
```

**Request payload example**

```json
{
  "jsonPolicies": [{
    "type": "masking",
    "rules": [{
      "type": "masking",
      "config": {
        "fields": ["amount"],
        "maskingConfig": {
          "type": "Consistent Value",
          "metadata": {
            "constant": null
          }
        }
      },
      "exceptions": null
    }],
    "createdAt": "2021-09-20T20:03:18.001Z",
    "createdBy": 2,
    "description": null
  }, {
    "type": "masking",
    "rules": [{
      "type": "masking",
      "config": {
        "fields": ["geo_latitude"],
        "maskingConfig": {
          "type": "Consistent Value",
          "metadata": {}
        }
      },
      "exceptions": null
    }],
    "createdAt": "2021-09-20T20:02:02.213Z",
    "createdBy": 2,
    "description": null
  }, {
    "type": "prerequisite",
    "rules": [{
      "type": "prerequisite",
      "exceptions": null,
      "config": {
        "qualifications": {
          "operator": "and",
          "conditions": [{
            "type": "purposes",
            "value": "Re-identification Prohibited"
          }]
        }
      }
    }],
    "description": ""
  }],
  "dataSourcePolicyHandler": {
    "handlerId": 26,
    "visibilitySchema": {
      "fields": []
    }
  }
}
```

#### Response example

```json
{
  "id": 42,
  "dataSourceId": 2,
  "createdBy": 2,
  "ca": ["-----BEGIN CERTIFICATE-----\ncertificatedata\n-----END CERTIFICATE-----"],
  "jsonPolicies": [
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "amount"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {
                "constant": null
              }
            }
          },
          "exceptions": null
        }
      ],
      "createdAt": "2021-09-20T20:03:18.001Z",
      "createdBy": 2,
      "description": null
    },
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "geo_latitude"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          },
          "exceptions": null
        }
      ],
      "createdAt": "2021-09-20T20:02:02.213Z",
      "createdBy": 2,
      "description": null
    },
    {
      "type": "prerequisite",
      "rules": [
        {
          "type": "prerequisite",
          "config": {
            "qualifications": {
              "operator": "and",
              "conditions": [
                {
                  "type": "purposes",
                  "value": "Re-identification Prohibited"
                }
              ]
            }
          },
          "exceptions": null
        }
      ],
      "createdAt": "2021-09-20T20:05:35.925Z",
      "createdBy": 2,
      "description": null
    }
  ],
  "createdAt": "2021-09-21T18:49:34.021Z",
  "updatedAt": "2021-09-21T18:49:34.021Z"
}
```

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

<mark style="color:green;">`POST`</mark> `/policy/global/applyPolicy`

Apply the Global Policy to the specified data source.

#### Query parameters

| Attribute | Description                                              | Required |
| --------- | -------------------------------------------------------- | -------- |
| payload   | `array` Contains Global Policy and data source metadata. | **Yes**  |

#### Payload parameters

| Attribute    | Description                                                 | Required |
| ------------ | ----------------------------------------------------------- | -------- |
| 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.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/policy/global/applyPolicy
```

**Request payload example**

The following payload will apply the Global Policy with the ID `1` to the data source with ID `1`.

```json
{
  "policyId": 1,
  "dataSourceId": 1,
  "merged": false
}
```

### Update a global policy

<mark style="color:green;">`PUT`</mark> `/policy/global/{policyId}`

Update the specified policy.

#### Query parameters

| Attribute | Description                                               | Required |
| --------- | --------------------------------------------------------- | -------- |
| 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](https://documentation.immuta.com/2024.3/developer-guides/api-intro/immuta-v1-api/manage-data-access/policy-handler) 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.

```shell
curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/policy/global/8
```

**Request payload example**

In this payload, the user updated the `description` attribute to update the policy.

```json
{
  "id": 8,
  "policyKey": "Mask Passports",
  "name": "Mask Passport",
  "type": "data",
  "template": false,
  "staged": false,
  "systemGenerated": false,
  "deleted": false,
  "certification": {
    "tags": ["Discovered.Passport"],
    "text": "This certifies that all columns containing passports in this data source have been tagged appropriately.",
    "label": "Certified"
  },
  "actions": [{
    "type": "masking",
    "rules": [{
      "type": "masking",
      "config": {
        "fields": [{
          "name": "Discovered.Passport",
          "source": "curated",
          "hasLeafNodes": false,
          "displayName": "Discovered > Passport"
        }],
        "maskingConfig": {
          "type": "Consistent Value",
          "metadata": {}
        }
      },
      "exceptions": null
    }],
    "description": "This policy masks all passports for data sources with columns tagged Discovered.Passport."
  }],
  "circumstances": [{
    "type": "columnTags",
    "operator": "or",
    "columnTag": {
      "name": "Discovered.Passport",
      "hasLeafNodes": false,
      "displayName": "Discovered > Passport"
    }
  }],
  "metadata": null,
  "clonedFrom": null,
  "createdBy": 2,
  "createdAt": "2021-09-21T18:35:48.615Z",
  "updatedAt": "2021-09-21T18:41:36.054Z",
  "createdByName": "Katie",
  "ownerRestrictions": null
}
```

#### Response example

```json
{
  "id": 6,
  "policyKey": "mask-passports",
  "name": "Mask Passports",
  "type": "data",
  "template": false,
  "createdBy": 2,
  "createdByName": "Kate",
  "createdAt": "2021-09-14",
  "updatedAt": "2021-09-15",
  "actions": [
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "exceptions": null,
          "config": {
            "fields": [
              {
                "name": "Discovered.Passport",
                "hasLeafNodes": false,
                "source": "curated"
              }
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          }
        }
      ],
      "description": "This policy masks all passports for data sources with columns tagged Discovered.Passport."
      }
    ],
      "circumstances": [
        {
          "operator": "or",
          "type": "columnTags",
          "columnTag": {
            "name": "Discovered.Passport",
            "hasLeafNodes": false
          }
        }
      ],
  "clonedFrom": 0,
  "staged": false,
  "systemGenerated": false,
  "deleted": false,
  "certification": {
    "label": "string",
    "text": "string",
    "tags": [
      "string"
    ],
    "recertify": false
  }
}
```

## Review policies

| Method | Path                                        | Purpose                                                                                                                                         |
| ------ | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/policy/search`                            | [Search all policies](#search-for-policies).                                                                                                    |
| GET    | `/policy/global/{policyId}`                 | [Find the policy with the specified ID](#find-policies-by-policy-id).                                                                           |
| GET    | `/policy/global`                            | [Find a list of Global Policies with the specified `entityType`](#find-policies-by-entity-type).                                                |
| GET    | `/policy/global/appliedTo/{policyId}`       | [Find the number of data sources the specified policy is currently applied to](#find-the-number-of-data-sources-a-specified-policy-applies-to). |
| GET    | `/policy/dataSourcePolicies/{dataSourceId}` | [Get the policy information for the specified data source](#get-the-policy-information-for-a-specific-data-source).                             |
| GET    | `/policy/diff/{dataSourceId}`               | [Get the differences between two policy handler versions](#get-the-differences-between-two-policy-versions).                                    |
| GET    | `/policy/handler/{dataSourceId}`            | [Get the policy handler metadata for a specific data source](#get-the-policy-handler-metadata-for-a-specific-data-source).                      |

### Search for policies

<mark style="color:green;">`POST`</mark> `/policy/search`

Searches for specified policies.

#### Query parameters

| Attribute        | Description                                                                                                                                 | Required |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| 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

| Attribute | Description                                                                               |
| --------- | ----------------------------------------------------------------------------------------- |
| 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.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/policy/search?scope=global&searchText=mask
```

#### Response example

```json
{
  "count": 1,
  "hits": [{
    "name": "Mask Passports",
    "createdBy": "Katie",
    "state": "active",
    "isNotApplied": false,
    "scope": "global",
    "type": "data",
    "globalPolicyId": 8,
    "policyId": null,
    "dataSourceId": null,
    "createdAt": "2021-09-21T18:35:48.615Z",
    "detailLabels": {
      "ruleType": ["masking"],
      "tags": ["Discovered.Passport"]
    },
    "enforcedOn": {
      "count": 1,
      "hits": [{
        "id": 1,
        "name": "Public Credit Accounts"
      }]
    }
  }]
}
```

### Find policies by policy ID

<mark style="color:green;">`GET`</mark> `/policy/global/{policyId}`

Find the policy with the specified ID.

#### Query parameters

| Attribute | Description                            | Required |
| --------- | -------------------------------------- | -------- |
| policyId  | `integer` The ID of the Global Policy. | **Yes**  |

#### Response parameters

The response returns a [policy object](https://documentation.immuta.com/2024.3/developer-guides/api-intro/immuta-v1-api/manage-data-access/policy-handler).

#### Request example

This example request returns the Global Policy with the ID `1`.

```shell
curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/policy/global/1
```

#### Response example

```json
{
  "id": 1,
  "policyKey": "New Column Added",
  "name": "New Column Added",
  "type": "data",
  "template": false,
  "staged": false,
  "systemGenerated": true,
  "deleted": false,
  "certification": null,
  "actions": [
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              {
                "name": "New",
                "source": "curated",
                "hasLeafNodes": false
              }
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {
                "constant": null
              }
            }
          },
          "exceptions": null
        }
      ],
      "description": null
    }
  ],
  "circumstances": [
    {
      "type": "columnTags",
      "operator": "or",
      "columnTag": {
        "name": "New",
        "hasLeafNodes": false
      }
    }
  ],
  "metadata": null,
  "clonedFrom": null,
  "createdBy": 1,
  "createdAt": "2021-09-09T13:47:03.448Z",
  "updatedAt": "2021-09-16T14:10:05.694Z",
  "createdByName": "Immuta System Account",
  "ownerRestrictions": null
}
```

### Find policies by entity type

<mark style="color:green;">`GET`</mark> `/policy/global`

Find the policy with the specified entity type.

#### Query parameters

| Attribute  | Description                                                                                                          | Required |
| ---------- | -------------------------------------------------------------------------------------------------------------------- | -------- |
| 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

| Attribute | Description                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------ |
| 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.

```shell
curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/policy/global?nameOnly=true
```

#### Response example

```json
[
  {
    "name": "Mask Passports",
    "id": 6,
    "type": "data"
  },
  {
    "name": "New Column Added",
    "id": 1,
    "type": "data"
  }
]
```

### Find the number of data sources a specified policy applies to

<mark style="color:green;">`GET`</mark> `/policy/global/appliedTo/{policyId}`

Find the number of data sources the specified policy applies to.

#### Query parameters

| Attribute | Description                            | Required |
| --------- | -------------------------------------- | -------- |
| policyId  | `integer` The ID of the Global Policy. | **Yes**  |

#### Response parameters

| Attribute | Description                                                 |
| --------- | ----------------------------------------------------------- |
| 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.

```shell
curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/policy/global/appliedTo/6
```

#### Response example

```json
{
  "count": 1
}
```

### Get the policy information for a specific data source

<mark style="color:green;">`GET`</mark> `/policy/dataSourcePolicies/{dataSourceId}`

Get the policy information for the specified data source.

#### Query parameters

| Attribute     | Description                                                                      | Required |
| ------------- | -------------------------------------------------------------------------------- | -------- |
| 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       |

#### Response parameters

| Attribute | Description                                                                                                 |
| --------- | ----------------------------------------------------------------------------------------------------------- |
| body      | `array` Contains policy metadata, including the policy `type`, `rules`, `exceptions`, and date of creation. |

#### Request example

This example request returns the information of policies applied to the data source with the ID `2`.

```shell
curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/policy/dataSourcePolicies/2
```

#### Response example

```json
[
  {
    "type": "masking",
    "rules": [
      {
        "type": "masking",
        "config": {
          "fields": [
            "amount"
          ],
          "maskingConfig": {
            "type": "Consistent Value",
            "metadata": {
              "constant": null
            }
          }
        },
        "exceptions": null
      }
    ],
    "createdAt": "2021-09-20T20:03:18.001Z",
    "createdBy": 2,
    "description": null
  },
  {
    "type": "masking",
    "rules": [
      {
        "type": "masking",
        "config": {
          "fields": [
            "geo_latitude"
          ],
          "maskingConfig": {
            "type": "Consistent Value",
            "metadata": {}
          }
        },
        "exceptions": null
      }
    ],
    "createdAt": "2021-09-20T20:02:02.213Z",
    "createdBy": 2,
    "description": null
  },
  {
    "type": "prerequisite",
    "rules": [
      {
        "type": "prerequisite",
        "config": {
          "qualifications": {
            "operator": "and",
            "conditions": [
              {
                "type": "purposes",
                "value": "Re-identification Prohibited"
              }
            ]
          }
        },
        "exceptions": null
      }
    ],
    "createdAt": "2021-09-20T20:05:35.925Z",
    "createdBy": 2,
    "description": null
  }
]
```

### Get the differences between two policy versions

<mark style="color:green;">`GET`</mark> `/policy/diff/{dataSourceId}`

Get the differences between two policy handler versions.

#### Query parameters

| Attribute         | Description                              | Required |
| ----------------- | ---------------------------------------- | -------- |
| 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       |

#### Response parameters

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

```shell
curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/policy/diff/3?currentHandlerId=47&previousHandlerId=46
```

#### Response example

```json
{
  "current": [{
    "type": "rowOrObjectRestriction",
    "rules": [{
      "type": "visibility",
      "config": {
        "predicate": "(`city` in (@groups()))",
        "qualifications": {
          "operator": "and",
          "conditions": [{
            "type": "groups",
            "field": "city"
          }]
        }
      },
      "exceptions": null
    }],
    "createdAt": "2021-09-28T18:46:00.868Z",
    "createdBy": 2,
    "description": null
  }],
  "previous": [{
    "type": "rowOrObjectRestriction",
    "rules": [{
      "type": "visibility",
      "config": {
        "predicate": "(`city` in (@groups()))",
        "qualifications": {
          "operator": "and",
          "conditions": [{
            "type": "groups",
            "field": "city"
          }]
        }
      },
      "exceptions": null
    }],
    "createdAt": "2021-09-28T18:46:00.868Z",
    "createdBy": 2,
    "description": null
  }],
  "hasChanges": false
}
```

### Get the policy handler metadata for a specific data source

<mark style="color:green;">`GET`</mark> `/policy/handler/{dataSourceId}`

Get the policy handler metadata for a specific data source.

#### Query parameters

| Attribute    | Description                          | Required |
| ------------ | ------------------------------------ | -------- |
| dataSourceId | `integer` The ID of the data source. | **Yes**  |

#### Response parameters

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

```shell
curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/policy/handler/1
```

#### Response example

```json
{
  "id": 44,
  "dataSourceId": 1,
  "rules": "rule masking_0_0 {  when { model_0_0 : MaskingModel ; } then { Masked(model_0_0, 0, 0) } } rule masking_5_0 {  when { model_5_0 : MaskingModel ; } then { Masked(model_5_0, 5, 0) } } rule masking_6_0 {  when { model_6_0 : MaskingModel ; } then { Masked(model_6_0, 6, 0) } }",
  "jsonPolicies": [
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "email"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {
                "constant": null
              }
            }
          },
          "exceptions": null
        }
      ],
      "createdAt": "2021-09-21T19:27:27.589Z",
      "createdBy": 2,
      "description": null
    },
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "email"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          },
          "exceptions": null
        }
      ],
      "global": {
        "id": 0,
        "tag": "Discovered.Passport",
        "name": "string",
        "reason": "test",
        "staged": false,
        "deleted": false,
        "conflict": "existingMasking",
        "disabled": true,
        "metadata": {
          "HEDReportVersion": "string",
          "certificationExpirationInterval": "string"
        },
        "template": false,
        "createdAt": "2021-09-14T00:00:00.000Z",
        "createdBy": "Katie",
        "policyKey": "string",
        "updatedAt": "2021-09-14T00:00:00.000Z",
        "clonedFrom": 0,
        "certification": true,
        "createdByName": "Katie",
        "changedOnApply": [],
        "systemGenerated": false,
        "ownerRestrictions": null
      },
      "description": null
    },
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "last_name"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          },
          "exceptions": null
        }
      ],
      "global": {
        "id": 0,
        "tag": "Discovered.Passport",
        "name": "string",
        "reason": "test",
        "staged": false,
        "deleted": false,
        "conflict": null,
        "disabled": true,
        "metadata": {
          "HEDReportVersion": "string",
          "certificationExpirationInterval": "string"
        },
        "template": false,
        "createdAt": "2021-09-14T00:00:00.000Z",
        "createdBy": "Katie",
        "policyKey": "string",
        "updatedAt": "2021-09-14T00:00:00.000Z",
        "clonedFrom": 0,
        "certification": true,
        "createdByName": "Katie",
        "changedOnApply": [],
        "systemGenerated": false,
        "ownerRestrictions": null
      },
      "description": null
    },
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "ssn"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          },
          "exceptions": null
        }
      ],
      "global": {
        "id": 0,
        "tag": "Discovered.Passport",
        "name": "string",
        "reason": "test",
        "staged": false,
        "deleted": false,
        "conflict": null,
        "disabled": true,
        "metadata": {
          "HEDReportVersion": "string",
          "certificationExpirationInterval": "string"
        },
        "template": false,
        "createdAt": "2021-09-14T00:00:00.000Z",
        "createdBy": "Katie",
        "policyKey": "string",
        "updatedAt": "2021-09-14T00:00:00.000Z",
        "clonedFrom": 0,
        "certification": true,
        "createdByName": "Katie",
        "changedOnApply": [],
        "systemGenerated": false,
        "ownerRestrictions": null
      },
      "description": null
    },
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "email"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          },
          "exceptions": null
        }
      ],
      "global": {
        "id": 8,
        "tag": "Discovered.Passport",
        "name": "Mask Passports",
        "reason": null,
        "staged": false,
        "deleted": false,
        "conflict": "existingMasking",
        "disabled": true,
        "metadata": null,
        "template": false,
        "createdAt": "2021-09-21T18:35:48.615Z",
        "createdBy": "Katie",
        "policyKey": "Mask Passport",
        "updatedAt": "2021-09-21T18:41:54.299Z",
        "clonedFrom": null,
        "certification": true,
        "createdByName": "Katie",
        "changedOnApply": [],
        "systemGenerated": false,
        "ownerRestrictions": null
      },
      "description": "This policy masks all passports for data sources with columns tagged Discovered.Passport."
    },
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "last_name"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          },
          "exceptions": null
        }
      ],
      "global": {
        "id": 8,
        "tag": "Discovered.Passport",
        "name": "Mask Passport",
        "reason": null,
        "staged": false,
        "deleted": false,
        "conflict": null,
        "disabled": false,
        "metadata": null,
        "template": false,
        "createdAt": "2021-09-21T18:35:48.615Z",
        "createdBy": "Katie",
        "policyKey": "Mask Passport",
        "updatedAt": "2021-09-21T18:41:54.299Z",
        "clonedFrom": null,
        "certification": true,
        "createdByName": "Katie",
        "changedOnApply": [],
        "systemGenerated": false,
        "ownerRestrictions": null
      },
      "description": "This policy masks all passports for data sources with columns tagged Discovered.Passport."
    },
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              "ssn"
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          },
          "exceptions": null
        }
      ],
      "global": {
        "id": 8,
        "tag": "Discovered.Passport",
        "name": "Mask Passport",
        "reason": null,
        "staged": false,
        "deleted": false,
        "conflict": null,
        "disabled": false,
        "metadata": null,
        "template": false,
        "createdAt": "2021-09-21T18:35:48.615Z",
        "createdBy": "Katie",
        "policyKey": "Mask Passports",
        "updatedAt": "2021-09-21T18:41:54.299Z",
        "clonedFrom": null,
        "certification": true,
        "createdByName": "Katie",
        "changedOnApply": [],
        "systemGenerated": false,
        "ownerRestrictions": null
      },
      "description": "This policy masks all passports for data sources with columns tagged Discovered.Passport."
    }
  ],
  "createdAt": "2021-09-21T19:27:27.977Z",
  "updatedAt": "2021-09-21T19:27:27.977Z"
}
```

## Delete a global policy

<mark style="color:green;">`DELETE`</mark> `/policy/global/{policyId}`

Delete the specified Global Policy.

#### Query parameters

| Attribute | Description                     | Required |
| --------- | ------------------------------- | -------- |
| policyId  | `integer` The ID of the policy. | **Yes**  |

#### Response parameters

The response returns a [policy object](https://documentation.immuta.com/2024.3/developer-guides/api-intro/immuta-v1-api/manage-data-access/policy-handler) of the policy that was deleted.

### Request example

The following request deletes the Global Policy with ID `6`.

```shell
curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/policy/global/6
```

### Response example

```json
{
  "id": 6,
  "policyKey": "mask-passports",
  "name": "Mask Passports",
  "type": "data",
  "template": false,
  "staged": false,
  "systemGenerated": false,
  "deleted": false,
  "certification": {
    "tags": [
      "string"
    ],
    "text": "string",
    "label": "string"
  },
  "actions": [
    {
      "type": "masking",
      "rules": [
        {
          "type": "masking",
          "config": {
            "fields": [
              {
                "name": "Discovered.Passport",
                "source": "curated",
                "hasLeafNodes": false
              }
            ],
            "maskingConfig": {
              "type": "Consistent Value",
              "metadata": {}
            }
          },
          "exceptions": null
        }
      ],
      "description": "This policy masks all passports for data sources with columns tagged Discovered.Passport."
    }
  ],
  "circumstances": [
    {
      "type": "columnTags",
      "operator": "or",
      "columnTag": {
        "name": "Discovered.Passport",
        "hasLeafNodes": false
      }
    }
  ],
  "metadata": null,
  "clonedFrom": 0,
  "createdBy": 2,
  "createdAt": "2021-09-14T00:00:00.000Z",
  "updatedAt": "2021-09-15T18:46:17.661Z",
  "createdByName": "Katie",
  "ownerRestrictions": null
}
```