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.

HTTP
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, and select the target workspace.

First select a role. Then view data privileges, confirm the current grant state, and prepare changes from the latest state.

Request parameters

Shell
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}]}'

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.

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":[]}}

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

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

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. Continue viewing while processing has not ended; confirm the grant only after processing is complete.

Last updated on