# Apply data privileges

Submit data-access privilege changes for a role. After acceptance, a change can still be processing; view its result before confirming that grants are complete.

```text
PUT $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/iam/roles/{role_id}/data-privileges
```

## Before you call this API

Configure the [regional API endpoint and authentication](https://omnifabric.cloudsigma.com/docs/developer/endpoints-and-authentication.html.md), and select the target workspace.

First [select a role](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/users-and-permissions/roles/list-roles.html.md#select-a-role). Then [view data privileges](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/users-and-permissions/data-privileges/get-data-privileges.html.md#confirm-current-data-privileges), confirm the current grant state, and prepare changes from the latest state.

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Input example

```bash
curl -X PUT "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID/data-privileges" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"req-001","expected_data_privilege_version":1,"mutations":[{"operation":"grant","action_id":"table.query","resource_type":"table","resource_id":"table-001","privilege":"select","with_grant_option":false}]}'
```

:::::
:::::{tab-item} Parameter description

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | Yes | Target workspace ID. |
| `role_id` | string | Yes | Role ID whose data privileges are updated. |

### Request body

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | Yes | Caller-generated idempotency request ID; also used to view the operation later. |
| `expected_data_privilege_version` | integer | No | Data-privilege version used for concurrency checks; cannot be less than 0. |
| `mutations` | object array | Yes | Privilege changes to perform; must contain at least one item. |
| `mutations[].operation` | string | Yes | Change type: `grant` or `revoke`. |
| `mutations[].action_id` | string | Yes | Data action ID in the permission schema. |
| `mutations[].resource_type` | string | Yes | Resource type: `database` or `table`. |
| `mutations[].resource_id` | string | Yes | Database or table resource ID. |
| `mutations[].privilege` | string | Yes | OmniFabric privilege name. |
| `mutations[].with_grant_option` | boolean | No | Whether the target role can grant this privilege onward. |
| `mutations[].row_column` | object | No | Table row/column rule; submit only to set, clear, or retain one. |
| `mutations[].row_column.mode` | string | Yes | Row/column rule handling: `keep`, `set`, or `clear`. |
| `mutations[].row_column.draft` | object | No | Row/column rule submitted when `mode` is `set`. |

:::::
::::::
:::::::

## Successful response

Returns the data-privilege operation and the execution status for each resource. `applying` means the request is accepted but not complete; view the operation with the original request ID until its state changes.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{"code":"OK","msg":"OK","data":{"request_id":"req-001","trace_id":"trace-001","operation_id":"operation-001","audit_event_id":"audit-001","state":"succeeded","data_privilege_version":2,"idempotent_replay":false,"session_invalidation_status":"new_connections_only","matrixone_fact_version":"fact-v2","resource_results":[]}}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.request_id` | string | Original request ID used to view this operation. |
| `data.operation_id` | string | Server-generated operation ID. |
| `data.audit_event_id` | string | Audit event ID. |
| `data.state` | string | Operation state: `applying`, `succeeded`, `failed`, `drifted`, or `unknown`. |
| `data.data_privilege_version` | integer | Data-privilege version after the operation. |
| `data.idempotent_replay` | boolean | Whether this is an idempotent replay of the same request. |
| `data.session_invalidation_status` | string | Session privilege refresh status. |
| `data.matrixone_fact_version` | string | OmniFabric privilege fact version. |
| `data.resource_results` | object array | Privilege execution result for each resource. |
| `data.trace_id` | string | Trace ID. |

:::::
::::::
:::::::

## Error response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{"code":"ErrParamInvalid","msg":"Invalid request parameters","data":null}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code. |
| `msg` | string | Error message. |
| `data` | null | — |

:::::
::::::
:::::::

## Next steps

### Continue tracking the change

Use this change identifier to [view the data privilege operation](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/users-and-permissions/data-privileges/get-data-privilege-operation.html.md#select-the-change-to-track). Continue viewing while processing has not ended; confirm the grant only after processing is complete.