# Create a Subscription Policy

## <mark style="color:green;">POST</mark> `/api/v2/policy`

**Required Immuta permission**: `GOVERNANCE`

{% tabs %}
{% tab title="Anyone" %}
Create an [Anyone can subscribe subscription policy](https://documentation.immuta.com/2025.1/governance/author-policies-for-data-access-control/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies).

```yaml
name: Anyone
policyKey: subscription anyone
type: subscription
actions:
  type: anyone
  automaticSubscription: false
  description: Rationale
circumstances:
  - type: tags
    tag: Discovered
```

{% endtab %}

{% tab title="Require approval" %}
Create an [anyone can subscribe when approved subscription policy](https://documentation.immuta.com/2025.1/governance/author-policies-for-data-access-control/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies).

```yaml
name: Approval
policyKey: subscription approval
type: subscription
actions:
  type: approval
  approvals:
    - specificApproverRequired: false
      requiredPermissions: OWNER
    - specificApproverRequired: true
      requiredPermissions: GOVERNANCE
  description: Rationale
circumstances:
  - type: columnTags
    columnTag: Discovered
```

{% endtab %}

{% tab title="Require group or attribute" %}
Create a [users with specific groups or attributes subscription policy](https://documentation.immuta.com/2025.1/governance/author-policies-for-data-access-control/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies).

```yaml
name: Entitlement
policyKey: subscription entitlements
type: subscription
actions:
  type: entitlements
  entitlements:
    operator: any
    groups:
      - Employee
    attributes:
      - name: auth1
        value: SOMETHING_ELSE
  automaticSubscription: true
  allowDiscovery: false
  description: Some description here
circumstances:
  - type: columnRegex
    regex: ssn
    caseInsensitive: false
staged: false
```

{% endtab %}

{% tab title="Advanced policy" %}
Create a [users with specific groups or attributes subscription policy](https://documentation.immuta.com/2025.1/governance/author-policies-for-data-access-control/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies) using advanced functions.

```yaml
name: Advanced Entitlement
policyKey: subscription entitlements advanced boolean
type: subscription
actions:
  type: entitlements
  advanced: "@isInGroups('Engineers', 'Founders') AND @hasAttribute('Auth1', 'Super Secret')"
  automaticSubscription: true
  allowDiscovery: false
  description: Some description here
circumstances:
  - type: columnRegex
    regex: ssn
    caseInsensitive: false
staged: false
```

{% endtab %}

{% tab title="Manually select" %}
Create an [individual users you select subscription policy](https://documentation.immuta.com/2025.1/governance/author-policies-for-data-access-control/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies).

```yaml
name: Manual
policyKey: subscription manual
type: subscription
actions:
  type: manual
  description: Rationale
```

{% endtab %}
{% endtabs %}

## 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             | -             | <ul><li><code>subscription</code></li><li><code>data</code></li></ul> |
| [**actions**](#actions-object) `object`             | 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`         | <ul><li><code>all</code></li><li><code>any</code></li></ul>           |
| **staged** `boolean`                                | If `true`, this global policy is in a staged status.                                                                     | Optional             | `false`       | <ul><li><code>true</code></li><li><code>false</code></li></ul>        |
| [**certification**](#certification-object) `object` | Certification information for the global policy.                                                                         | Optional             | -             | -                                                                     |

### `actions` object

The **actions** object describes the rules of the policy.

| Attribute                                         | Description                                                                                                                                                                                                                                                                                                                                      | Required or optional                   | Default value | Accepted values                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type** `string`                                 | The type of subscription policy.                                                                                                                                                                                                                                                                                                                 | Required                               | -             | <ul><li><code>anyone</code>: Anyone can subscribe</li><li><code>approval</code>: Anyone can request approval and will be subscribed when it is approved</li><li><code>entitlements</code>: Users with the listed attributes or groups will be subscribed</li><li><code>manual</code>: Users must be manually added to be subscribed</li></ul> |
| **automaticSubscription** `boolean`               | When `true`, users will be automatically subscribed to the data source without having to take action.                                                                                                                                                                                                                                            | Optional                               | `false`       | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                                                                                                                                                                                                                                                                |
| **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.                                                                                                                                                                                                         | Optional                               | `false`       | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                                                                                                                                                                                                                                                                |
| **advanced** `string`                             | An advanced function to use as the subscription policy. See the [Advanced use of special functions guide](https://documentation.immuta.com/2025.1/governance/author-policies-for-data-access-control/authoring-policies-in-secure/section-contents/reference-guides/advanced-special-functions) for details about the functions Immuta supports. | Optional                               | -             | -                                                                                                                                                                                                                                                                                                                                             |
| **description** `string`                          | The rationale for your policy.                                                                                                                                                                                                                                                                                                                   | Optional                               | -             | -                                                                                                                                                                                                                                                                                                                                             |
| [**approvals**](#approvals-array) `array`         | Details about the user(s) that will approve subscription requests.                                                                                                                                                                                                                                                                               | Required if **type** is `approval`     | -             | -                                                                                                                                                                                                                                                                                                                                             |
| [**entitlements**](#entitlements-object) `object` | Details about the entitlements required for users to subscribe to the data sources.                                                                                                                                                                                                                                                              | Required if **type** is `entitlements` | -             | -                                                                                                                                                                                                                                                                                                                                             |

#### `approvals` array

This array is required if the policy **type** is `approval` in the [**actions** object](#actions-object). It allows you to define the users who can approve subscription requests.

| Attribute                              | Description                                                                                                                                                           | Required or optional | Default value | Accepted values                                                                                       |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| **specificApproverRequired** `boolean` | If `true`, the user to approve the request will be selected by the user requesting access. If `false`, any user with the required permission can approve the request. | Required             | -             | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                        |
| **requiredPermissions** `string`       | The required permissions for the user approving the subscription request.                                                                                             | Required             | -             | <ul><li><code>USER\_ADMIN</code></li><li><code>GOVERNANCE</code></li><li><code>AUDIT</code></li></ul> |

#### `entitlements` object

This object is required if the policy **type** is `entitlements` in the [**actions** object](#actions-object). It allows you to define the groups or attributes that users must have to subscribe to the project.

| Attribute                      | Description                                                                                                          | Required or optional                         | Default value | Accepted values                                             |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------- | ----------------------------------------------------------- |
| **operator** `string`          | Specifies whether users must have `all` or `any` of the entitlements to be eligible to subscribe to the data source. | Required                                     | -             | <ul><li><code>all</code></li><li><code>any</code></li></ul> |
| **groups** `array[string]`     | The names of the groups the user must be a member of to subscribe to the data source.                                | Requires either **groups** or **attributes** | -             | -                                                           |
| **attributes** `array[object]` | Details about attributes the user must have to subscribe to the data source.                                         | Requires either **groups** or **attributes** | -             | -                                                           |
| attributes.**name** `string`   | The name of the attribute the user must have to subscribe to the data source. This is commonly referred to as a key. | Required if using **attributes**             | -             | -                                                           |
| attributes.**value** `string`  | The value of the attribute the user must have to subscribe to the data source.                                       | Required if using **attributes**             | -             | -                                                           |

### `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 | <ul><li><code>tags</code>: Apply the policy when the data source has these tags.</li><li><code>columnRegex</code>: Apply the policy when the data source has column names that match the regex.</li><li><code>columnTags</code>: Apply the policy when the data source has columns with these tags.</li><li><code>domains</code>: Apply the policy to data sources in these domains.</li><li><code>null</code>: Apply the policy to data sources when it is selected by data owners.</li><li><code>server</code>: Apply the policy to data sources in this server.</li><li><code>time</code>: Apply the policy to data sources created in a specific time period.</li></ul> |
| **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 **type** `columnRegex`.                            | Optional                                                                     | -                            | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **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`       | <ul><li><code>true</code></li><li><code>false</code></li></ul> |