# Apply data privileges

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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 https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/iam/roles/{role_id}/data-privileges
```

## Preparation before calling

First [select a role](../roles/list-roles.md#select-a-role). Then [view data privileges](get-data-privileges.md#confirm-current-data-privileges), confirm the current grant state, and prepare changes from the latest state.

Prepare a [personal access token](../../../../../guides/genesis/api-keys.md) with the required permissions for the target workspace and the [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-a-workspace-id).

## Request parameters

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

```bash
curl -X PUT "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID/data-privileges" \
  -H "X-API-Key: $AI_STUDIO_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 | MatrixOne 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 | MatrixOne 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](get-data-privilege-operation.md#select-the-change-to-track). Continue viewing while processing has not ended; confirm the grant only after processing is complete.