> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/2024.3/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/2024.3/developer-guides/api-intro/immuta-v1-api/manage-data-access/write-policies-api.md).

# Manage Write Policies

Write policies API endpoint reference guide

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](/2024.3/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.

```shell
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"
    }'
```

### Request 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](/2024.3/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 the following JSON object. See the [payload reference guide](/2024.3/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.

{% 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.

```shell
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`.

```shell
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](/2024.3/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](/2024.3/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.

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

### Request 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](/2024.3/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.

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

### Request parameter

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

### Response

The response returns the global policy configuration. See the [payload reference guide](/2024.3/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;">`PUT`</mark> `/policy/global/{policyId}`

Updates the specified policy.

```shell
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](/2024.3/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](/2024.3/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.


---

# 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/2024.3/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.