Validate object grants¶

Check whether grant changes for one role on one object can be saved without modifying existing grants. Apply the changes separately after validation succeeds.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/iam/permissions/objects/{resource_type}/{resource_id}/roles/{role_id}/grants:validate

Preparation before calling¶

Select the object and role to grant, then view the object permission view to confirm the current grant state. Next, view the permission schema to select supported actions and grant scopes.

Prepare a personal access token with the required permissions for the target workspace and the target workspace ID.

Request parameters¶

Input example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/iam/permissions/objects/$RESOURCE_TYPE/$RESOURCE_ID/roles/$ROLE_ID/grants:validate" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "current-schema-version",
    "expected_policy_version": 1,
    "expected_role_lifecycle_version": 1,
    "request_id": "req-001",
    "changes": [{"remove": false, "action_id": "workflow.read"}]
  }'

Parameter description

Path parameters

Parameter	Type	Required	Description
`workspace_id`	string	Yes	Target workspace ID.
`resource_type`	string	Yes	Resource type of the target object.
`resource_id`	string	Yes	Resource ID of the target object.
`role_id`	string	Yes	Role ID receiving the grant changes.

Request body

Parameter	Type	Required	Description
`schema_version`	string	Yes	Permission schema version used by this change.
`expected_policy_version`	integer	No	Policy version used for concurrency checks; cannot be less than 0.
`expected_role_lifecycle_version`	integer	Yes	Current role lifecycle version; must be greater than 0.
`request_id`	string	Yes	Caller-generated request ID.
`changes`	object array	Yes	Grant changes to validate; must contain at least one item.
`changes[].remove`	boolean	No	`true` removes a grant; omitted or `false` adds a grant.
`changes[].action_id`	string	Yes	Action ID in the permission schema.
`changes[].condition_hash`	string	No	Hash of the condition expression.

Successful response¶

On success, returns a preview of the grant changes. validate_only is true; the policy is not saved.

Response example

{"code":"OK","msg":"OK","data":{"workspace_id":"workspace-001","resource_type":"workflow","resource_id":"workflow-001","target_role_id":"role-001","previous_policy_version":1,"policy_version":1,"statement_count":1,"added_count":1,"removed_count":0,"idempotent_replay":false,"canonical_policy_hash":"sha256:example","validate_only":true,"request_id":"req-001","trace_id":"trace-001"}}

Field details

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.workspace_id`	string	Target workspace ID.
`data.resource_type`	string	Target resource type.
`data.resource_id`	string	Target resource ID.
`data.target_role_id`	string	Role ID receiving the grant changes.
`data.previous_policy_version`	integer	Policy version before validation.
`data.policy_version`	integer	Policy version used by validation; validation does not increment it.
`data.statement_count`	integer	Number of policy statements after the change.
`data.added_count`	integer	Number of statements that would be added.
`data.removed_count`	integer	Number of statements that would be removed.
`data.canonical_policy_hash`	string	Hash of the normalized policy.
`data.validate_only`	boolean	Always `true` for this endpoint.
`data.request_id`	string	Request correlation ID.
`data.trace_id`	string	Trace ID.

Error response¶

Response example

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

Field details

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

Last updated on Sep 3, 2026