Apply object grants¶

Save the complete grant changes for one role on one object. Saving changes the actions available to that role on the object.

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

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 PUT "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/iam/permissions/objects/$RESOURCE_TYPE/$RESOURCE_ID/roles/$ROLE_ID/grants" \
  -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 idempotency request ID.
`changes`	object array	Yes	Grant changes to save; 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, the grant changes are saved and a new policy version is returned. Replaying the same request ID with identical content does not apply the changes again.

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":2,"statement_count":1,"added_count":1,"removed_count":0,"idempotent_replay":false,"canonical_policy_hash":"sha256:example","validate_only":false,"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 the update.
`data.policy_version`	integer	Policy version after the update.
`data.statement_count`	integer	Number of policy statements after the update.
`data.added_count`	integer	Number of added statements.
`data.removed_count`	integer	Number of removed statements.
`data.idempotent_replay`	boolean	Whether this is an idempotent replay of the same request.
`data.canonical_policy_hash`	string	Hash of the policy after saving.
`data.validate_only`	boolean	Always `false` 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