# Write Policies Payloads and Response Schema Reference Guide

## Manual write access grant payload

The parameters for manually granting write access to a data source without using a policy are outlined in the table below.

| Parameter                | Description                                                              | Required or optional | Default values | Accepted values                                                                                  |
| ------------------------ | ------------------------------------------------------------------------ | -------------------- | -------------- | ------------------------------------------------------------------------------------------------ |
| **profileId** `integer`  | The unique identifier of the user to whom you are granting write access. | Required             | -              | -                                                                                                |
| **state** `string`       | The user's role on the data source.                                      | Required             | -              | <ul><li><code>expert</code></li><li><code>owner</code></li><li><code>subscribed</code></li></ul> |
| **accessGrant** `string` | The type of access to grant the user.                                    | Required             | -              | <ul><li><code>READ</code></li><li><code>WRITE</code></li></ul>                                   |

## Global write policy payload

The parameters for creating a global write policy are outlined in the table below.

| Parameter                                           | Description                                                                                                                                                                                                                                                                                                                                                | Required or optional | Default values                                      | Accepted values                                                |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------- | -------------------------------------------------------------- |
| **type** `string`                                   | The type of policy to create.                                                                                                                                                                                                                                                                                                                              | Required             | -                                                   | `subscription`                                                 |
| **name** `string`                                   | The name of the policy.                                                                                                                                                                                                                                                                                                                                    | Required             | -                                                   | -                                                              |
| **template** `boolean`                              | Specifies whether or not the policy should be available as a template.                                                                                                                                                                                                                                                                                     | Optional             | `false`                                             | <ul><li><code>true</code></li><li><code>false</code></li></ul> |
| [**actions** `array[]`](#actions-array)             | Specifies the policy access type and restriction level. See the [array description](#actions-array) for details.                                                                                                                                                                                                                                           | Required             | -                                                   |                                                                |
| **staged** `boolean`                                | When `true`, the policy is not active or applied to any data sources.                                                                                                                                                                                                                                                                                      | Required             | -                                                   | <ul><li><code>true</code></li><li><code>false</code></li></ul> |
| [**circumstances** `object`](#circumstances-object) | This object specifies the conditions under which the policy applies to a data source. Set the value to `null` to enforce the policy only when it is applied by data owners. Do not include this object in your payload to apply the policy to all data sources. See the [object description](#circumstances-object) for additional parameters and details. | Optional             | By default, the policy applies to all data sources. | -                                                              |

### Actions array

The **actions** array specifies the policy access type and restriction level. Its child parameters are outlined in the table below.

<table><thead><tr><th>Parameter</th><th>Description</th><th>Required or optional</th><th width="149">Default values</th><th>Accepted values</th></tr></thead><tbody><tr><td><strong>type</strong> <code>string</code></td><td>The type of policy. For write access policies, the <strong>type</strong> is <code>subscription</code>.</td><td>Required</td><td>-</td><td><ul><li><code>data</code></li><li><code>subscription</code></li></ul></td></tr><tr><td><strong>accessGrant</strong> <code>string</code></td><td>The type of access the user is granted.</td><td>Required</td><td>-</td><td><code>WRITE</code></td></tr><tr><td><strong>description</strong> <code>string</code></td><td>The description of the policy.</td><td>Optional</td><td><code>null</code></td><td>-</td></tr><tr><td><strong>subscriptionType</strong> <code>string</code></td><td>The restriction level of the subscription policy.</td><td>Required</td><td>-</td><td><ul><li><code>approval</code>: Users are granted access when approved by a specified user</li><li><code>automatic</code>: Anyone is granted access</li><li><code>manual</code>: Individually selected users are granted access</li><li><code>policy</code>: Users with specified entitlements are granted access</li></ul></td></tr></tbody></table>

### Circumstances object

The **circumstances** object specifies the conditions under which the policy applies to a data source. Its child parameters are outlined in the table below.

| Parameter                                 | Description                                                                                                                                                      | Required or optional                     | Default values | Accepted values                                                                                                                                                                                                    |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **operator** `string`                     | Specifies how to combine the conditions of the policy.                                                                                                           | Required                                 | -              | <ul><li><code>and</code></li><li><code>or</code></li></ul>                                                                                                                                                         |
| **type** `string`                         | The type of condition under which to apply the policy.                                                                                                           | Required                                 | -              | <ul><li><code>anyTag</code></li><li><code>columnRegex</code></li><li><code>columnTags</code></li><li><code>noTags</code></li><li><code>server</code></li><li><code>tags</code></li><li><code>time</code></li></ul> |
| **columnRegex** `object`                  | This object indicates that the policy should apply to data sources with column names that match the regular expression. Its child parameters are outlined below. | Required when **type** is `columnRegex`. | -              | -                                                                                                                                                                                                                  |
| columnRegex.**regex** `string`            | A regular expression that matches names of columns.                                                                                                              | Required when **type** is `columnRegex`. | -              | -                                                                                                                                                                                                                  |
| columnRegex.**caseInsensitive** `boolean` | When `true`, the regular expression is case insensitive.                                                                                                         | Optional                                 | `false`        | <ul><li><code>true</code></li><li><code>false</code></li></ul>                                                                                                                                                     |
| **columnTag** `object`                    | This object specifies the column tags required for the policy to apply to the data source. Child parameters are outlined below.                                  | Required if **type** is `columnTags`.    | -              | -                                                                                                                                                                                                                  |
| columnTag.**name** `string`               | The name of the tag.                                                                                                                                             | Required if **type** is `columnTags`     | -              | -                                                                                                                                                                                                                  |
| columnTag.**displayName** `string`        | The display name of the tag.                                                                                                                                     | Optional                                 | -              | -                                                                                                                                                                                                                  |
| columnTag.**hasLeafNodes** `boolean`      | When `true`, the tag applied has child tags.                                                                                                                     | Optional                                 | -              | -                                                                                                                                                                                                                  |
| **server** `string`                       | The server that contains the data sources the policy should be applied to.                                                                                       | Required when **type** is `server`.      | -              | -                                                                                                                                                                                                                  |
| **startDate** `string`                    | Applies the policy to data sources created on or after this **startDate** and before the **endDate** (if the **endDate** is specified).                          | Required when **type** is `time`.        | -              | -                                                                                                                                                                                                                  |
| **endDate** `string`                      | Applies the policy to data sources created on or before this **endDate** and after the **startDate**.                                                            | Optional                                 | `null`         | -                                                                                                                                                                                                                  |

## Global write policy response schema

| Parameter                                   | Description                                                                                                                                                                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **policyKey** `string`                      | The unique name of the policy.                                                                                                                                                                                                               |
| **createdBy** `integer`                     | The unique identifier of the user who created the policy.                                                                                                                                                                                    |
| **createdByName** `string`                  | The username of the user who created the policy.                                                                                                                                                                                             |
| **createdAt** `string`                      | The date the policy was created.                                                                                                                                                                                                             |
| **clonedFrom** `integer`                    | The unique identifier of the policy that the new policy was cloned from.                                                                                                                                                                     |
| **systemGenerated** `boolean`               | Indicates whether or not the policy is system-generated.                                                                                                                                                                                     |
| **deleted** `boolean`                       | When `true`, the policy has been deleted.                                                                                                                                                                                                    |
| **id** `integer`                            | The unique identifier of the policy.                                                                                                                                                                                                         |
| **type** `string`                           | The type of policy. For write access policies, the **type** is `subscription`.                                                                                                                                                               |
| **name** `string`                           | The name of the policy.                                                                                                                                                                                                                      |
| **template** `boolean`                      | Specifies whether or not the policy is available as a template.                                                                                                                                                                              |
| **certification** `object`                  | The certification object only applies to data policies, not write access policies.                                                                                                                                                           |
| **actions** `array[]`                       | Specifies the policy access type and restriction level.                                                                                                                                                                                      |
| actions.**type** `string`                   | The type of policy. For write access policies, the **type** is `subscription`.                                                                                                                                                               |
| actions.**accessGrant** `string`            | The type of access the user is granted. For write access policies, **actions.accessGrant** is `WRITE`.                                                                                                                                       |
| actions.**description** `string`            | The description of the policy.                                                                                                                                                                                                               |
| actions.**allowDiscovery** `boolean`        | When `true`, users can still see that the data source exists in Immuta, even if they do not have the attributes and groups specified by the policy.                                                                                          |
| actions.**subscriptionType** `string`       | The restriction level of the subscription policy.                                                                                                                                                                                            |
| actions.**shareResponsibility** `boolean`   | When `true`, users need to meet the conditions in this policy OR another share responsibility policy that applies to the data source. This parameter is not applicable to policies with `actions.subscriptionType` with a value of `manual`. |
| actions.**automaticSubscription** `boolean` | When `true`, users will automatically be subscribed to the data source when they meet the conditions specified in the policy. This parameter is not applicable to policies with **actions.subscriptionType** with a value of `manual`.       |
| **staged** `boolean`                        | When `true`, the policy is staged and not active on any data sources.                                                                                                                                                                        |
| **circumstances** `array[]`                 | Specifies the conditions under which the policy applies to a data source. See the [object description](#circumstances-object) for child parameters.                                                                                          |

## Manual write access grant response schema

| Parameter                            | Description                                                                                                                             |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **isSubscriptionOverride** `boolean` | When `true`, the user was manually granted write access by a data owner instead of being granted access by a policy on the data source. |
| **id** `integer`                     | The unique identifier of the user's subscription to the data source.                                                                    |
| **modelId** `integer`                | The unique identifier of the data source.                                                                                               |
| **modelType** `string`               | The type of model the subscription policy applies to. For write policies, **modelType** is `dataSource`.                                |
| **state** `string`                   | The type of role the user has, such as `expert`, `owner`, or `subscribed`.                                                              |
| **admin** `integer`                  | The unique identifier of the user who granted write access to the data source subscriber.                                               |
| **denialReasoning** `string`         | If the user was denied access to the data source, this field contains the reason entered by the owner who denied access.                |
| **profile** `integer`                | The unique identifier of the user who has been granted write access.                                                                    |
| **group** `string`                   | The name of the group that has been granted write access, when applicable.                                                              |
| **policy** `boolean`                 | When `true`, the access has been granted by a policy on the data source.                                                                |
| **expiration** `string`              | The date the user's access expires.                                                                                                     |
| **acknowledgeRequired** `boolean`    | When `true`, the users must manually request access to the data source.                                                                 |
| **createdAt** `string`               | The date and time the user's access to the data source was granted.                                                                     |
| **updatedAt** `string`               | The date and time the user's access to the data source was updated.                                                                     |
| **accessGrant** `string`             | The type of access the user has to the data source: `READ` or `WRITE`.                                                                  |
| **approved** `boolean`               | When `true`, the user's access to the data source has been approved.                                                                    |