> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v2-api/subscription-policy.md).

# Create a Subscription Policy

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

**Required Immuta permission**: `GOVERNANCE`

{% tabs %}
{% tab title="Require group or attribute" %}
Create a [users with specific groups or attributes subscription policy](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies.md).

```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](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies.md) 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](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies.md).

```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>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](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/advanced-special-functions.md) for details about the functions Immuta supports. | Optional                               | -             | -                                                                                                                                                                                     |
| **description** `string`                          | The rationale for your policy.                                                                                                                                                                                                                                                         | Optional                               | -             | -                                                                                                                                                                                     |
| [**entitlements**](#entitlements-object) `object` | Details about the entitlements required for users to subscribe to the data sources.                                                                                                                                                                                                    | Required if **type** is `entitlements` | -             | -                                                                                                                                                                                     |

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v2-api/subscription-policy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.