> 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-v1-api/manage-data-access/write-policies-api.md).

# Manage Write Policies

Understand the endpoints and parameters for managing write policies

The policies resource allows you to manage and apply policies to your data sources. The endpoints and examples provided in this guide are specific to creating [global write policies](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/subscription-access-types.md).

## Endpoints

<table><thead><tr><th>Method</th><th width="370">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><strong>POST</strong></td><td><a href="#post-datasource-datasourceid-access"><mark style="color:blue;"><code>/dataSource/{dataSourceId}/access</code></mark></a></td><td>Manually grants write access to a user</td></tr><tr><td><strong>POST</strong></td><td><a href="#post-policy-global"><mark style="color:blue;"><code>/policy/global</code></mark></a></td><td>Creates a global write access policy</td></tr><tr><td><strong>DELETE</strong></td><td><a href="#delete-policy-global-policyid"><mark style="color:blue;"><code>/policy/global/{policyId}</code></mark></a></td><td>Deletes the specified global write access policy</td></tr><tr><td><strong>GET</strong></td><td><a href="#get-policy-global-policyid"><mark style="color:blue;"><code>/policy/global/{policyId}</code></mark></a></td><td>Gets the global policy with the given policy ID</td></tr><tr><td><strong>PUT</strong></td><td><a href="#put-policy-global-policyid"><mark style="color:blue;"><code>/policy/global/{policyId}</code></mark></a></td><td>Updates the specified global policy</td></tr></tbody></table>

## <mark style="color:green;">`POST`</mark> `/dataSource/{dataSourceId}/access`

Manually grants write access to a user.

**Requirement**: `GOVERNANCE` permission, `USER_ADMIN` permission, or be the data source owner

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/dataSource/6/access' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "profileId": 3,
    "state": "subscribed",
    "accessGrant": "WRITE"
    }'
```

### Path parameter

| Parameter                  | Description                               |
| -------------------------- | ----------------------------------------- |
| **dataSourceId** `integer` | The unique identifier of the data source. |

### Body parameters

The request accepts a JSON or YAML payload. See the [write access manual grant payload description](/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md#manual-write-access-grant-payload) for parameter details.

### Response

The response returns a JSON object. See the [payload reference guide](/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md#manual-write-access-grant-response-schema) for details about the response schema.

```json
{
  "isSubscriptionOverride": true,
  "id": 23,
  "modelId": "6",
  "modelType": "datasource",
  "state": "subscribed",
  "metadata": {},
  "admin": 2,
  "denialReasoning": null,
  "profile": 3,
  "group": null,
  "policy": false,
  "expiration": null,
  "acknowledgeRequired": false,
  "createdAt": "2023-10-11T14:43:00.726Z",
  "updatedAt": "2023-10-11T14:43:00.726Z",
  "accessGrant": "WRITE",
  "approved": true
}
```

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

Creates a global policy.

**Requirement**: `GOVERNANCE` permission, domain-specific `Manage Policies` permission, or be a data source owner

{% tabs %}
{% tab title="Users with specific groups or attributes" %}
The example below grants write access to users with the attribute `has.write` and applies the global policy to all data sources.

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/policy/global' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "subscription",
    "name": "Allow users with specific entitlements to have write access",
    "actions": [{
      "type": "subscription",
      "subscriptionType": "policy",
      "accessGrant": "WRITE",
      "exceptions": {
        "operator": "and",
        "conditions": [{
          "type": "authorizations",
          "authorization": {
            "auth": "has",
            "value": "write"
          }
      }]
    }
    }],
    "staged": false
    }'
```

{% endtab %}

{% tab title="Individually selected users" %}
The example below grants users write access when they are individually selected by data owners and applies the policy to data sources with columns tagged `Discovered.Person Name`.

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/policy/global' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "subscription",
    "name": "Data owners grant specific users write access",
    "actions": [{
      "type": "subscription",
      "subscriptionType": "manual",
      "accessGrant": "WRITE"
    }],
    "staged": false,
    "circumstances": [{
    "type": "columnTags",
    "columnTag": {
      "name": "Discovered.Person Name",
      "displayName": "Discovered . Person Name",
      "hasLeafNodes": false
      }
    }]
    }'
```

{% endtab %}
{% endtabs %}

### Body parameters

The request accepts a JSON or YAML payload. See the [global policy payload description](/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md#global-write-policy-payload) for parameter details.

### Response

The response returns the global policy configuration. See the [payload reference guide](/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md#global-write-policy-response-schema) for details about the response schema.

{% tabs %}
{% tab title="Basic example" %}

```json
{
  "policyKey": "Manual global write policy",
  "name": "Manual global write policy",
  "type": "subscription",
  "template": true,
  "staged": false,
  "systemGenerated": false,
  "deleted": false,
  "certification": null,
  "actions": [
    {
      "type": "subscription",
      "accessGrant": "WRITE",
      "description": null,
      "allowDiscovery": false,
      "subscriptionType": "manual",
      "shareResponsibility": false,
      "automaticSubscription": false
    }
  ],
  "circumstances": null,
  "metadata": null,
  "clonedFrom": null,
  "createdBy": 2,
  "id": 4,
  "createdAt": "2023-10-10T13:18:37.270Z",
  "updatedAt": "2023-10-10T13:18:37.270Z",
  "createdByName": "Taylor",
  "ownerRestrictions": null
}
```

{% endtab %}

{% tab title="Complex example" %}

```json
{
  "policyKey": "Manual global write policy",
  "name": "Manual global write policy",
  "type": "subscription",
  "template": true,
  "staged": false,
  "systemGenerated": false,
  "deleted": false,
  "certification": null,
  "actions": [
    {
      "type": "subscription",
      "accessGrant": "WRITE",
      "description": null,
      "allowDiscovery": false,
      "subscriptionType": "manual",
      "shareResponsibility": false,
      "automaticSubscription": false
    }
  ],
  "circumstances": [{
    "type": "columnTags",
    "columnTag": {
      "name": "Discovered.Person Name",
      "displayName": "Discovered . Person Name",
      "hasLeafNodes": false
      }
    }],
  "metadata": null,
  "clonedFrom": null,
  "createdBy": 2,
  "id": 4,
  "createdAt": "2023-10-10T13:18:37.270Z",
  "updatedAt": "2023-10-10T13:18:37.270Z",
  "createdByName": "Taylor",
  "ownerRestrictions": null
}
```

{% endtab %}
{% endtabs %}

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

Deletes the specified policy.

**Requirement**: `GOVERNANCE` permission, domain-specific `Manage Policies` permission, or be the policy creator

```bash
curl -X 'DELETE' \
    'https://www.organization.immuta.com/policy/global/4' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'
```

### Path parameter

| Parameter              | Description                          |
| ---------------------- | ------------------------------------ |
| **policyId** `integer` | The unique identifier of the policy. |

### Response

The response returns the deleted global policy configuration. See the [payload reference guide](/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md#global-write-policy-response-schema) for details about the response schema.

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

Gets the specified policy.

```bash
curl -X 'GET' \
    'https://www.organization.immuta.com/policy/global/4' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'
```

### Path parameter

| Parameter              | Description                          |
| ---------------------- | ------------------------------------ |
| **policyId** `integer` | The unique identifier of the policy. |

### Response

The response returns the global policy configuration. See the [payload reference guide](/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md#global-write-policy-response-schema) for details about the response schema.

```json
{
  "policyKey": "Manual global write policy",
  "name": "Manual global write policy",
  "type": "subscription",
  "template": true,
  "staged": false,
  "systemGenerated": false,
  "deleted": false,
  "certification": null,
  "actions": [
    {
      "type": "subscription",
      "accessGrant": "WRITE",
      "description": null,
      "allowDiscovery": false,
      "subscriptionType": "manual",
      "shareResponsibility": false,
      "automaticSubscription": false
    }
  ],
  "circumstances": null,
  "metadata": null,
  "clonedFrom": null,
  "createdBy": 2,
  "id": 4,
  "createdAt": "2023-10-10T13:18:37.270Z",
  "updatedAt": "2023-10-10T13:18:37.270Z",
  "createdByName": "Taylor",
  "ownerRestrictions": null
}
```

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

Updates the specified policy.

**Requirement**: `GOVERNANCE` permission, domain-specific `Manage Policies` permission, or be the policy creator

```bash
curl -X 'PUT' \
    'https://www.organization.immuta.com/policy/global/4' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "subscription",
    "name": "Manual global write policy",
    "template": true,
    "actions": [{
      "type": "subscription",
      "subscriptionType": "manual",
      "description": "This updated policy only applies to data sources tagged Discovered.Healthcare NPI.",
      "accessGrant": "WRITE"
    }],
    "staged": false,
    "circumstances": [{
      "operator": "or",
      "type": "columnTags",
      "columnTag": {
        "name": "Discovered.Healthcare NPI",
        "displayName": "Discovered . Healthcare NPI",
        "hasLeafNodes": false
      }
    }]
    }'
```

### Body parameters

The request accepts a JSON or YAML payload. See the [global policy payload description](/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md#global-write-policy-payload) for parameter details.

### Response

The response returns the updated global policy configuration. See the [payload reference guide](/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api/payload-reference.md#global-write-policy-response-schema) for details about the response schema.

```json
{
  "policyKey": "Manual global write policy",
  "name": "Manual global write policy",
  "type": "subscription",
  "template": true,
  "staged": false,
  "systemGenerated": false,
  "deleted": false,
  "certification": null,
  "actions": [
    {
      "type": "subscription",
      "subscriptionType": "manual",
      "description": "This updated policy only applies to data sources tagged Discovered.Healthcare NPI.",
      "accessGrant": "WRITE"
    }
  ],
  "circumstances": [
    {
      "operator": "or",
      "type": "columnTags",
      "columnTag": {
        "name": "Discovered.Healthcare NPI",
        "displayName": "Discovered . Healthcare NPI",
        "hasLeafNodes": false
      }
    }
  ]
}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.