Create a role¶
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/iam/roles
Before you call this API¶
Prepare Workspace credentials, jq, and the permission definition’s SCHEMA_VERSION. The caller’s effective role must have role.create. Generate a REQUEST_ID of at most 64 UTF-8 bytes without whitespace/control characters. At least one user-selected initial application or data permission must be valid. The example grants access to view all workflows.
Request¶
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/iam/roles" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H 'Content-Type: application/json' \
--data-binary "$(jq -n --arg schema "$SCHEMA_VERSION" --arg request "$REQUEST_ID" '{name:"analyst",description:"Workflow readers",schema_version:$schema,request_id:$request,statements:[{action_id:"workflow.read",resource_type:"workflow",scope_mode:"all"}],data_privilege_mutations:[]}')"
Field |
Type |
Description |
|---|---|---|
name |
string, required |
1–255 UTF-8 bytes, without whitespace/control characters or system-reserved names. |
description |
string, optional |
At most 4096 UTF-8 bytes without NUL; omission/null becomes empty. |
schema_version |
string, required |
Current permission-definition fingerprint; the server validates intent against current definitions. |
request_id |
string, required |
Retain the original ID and identical content for the same creation and confirmation. |
statements |
object[] |
Initial application policy; see shared objects for all fields. |
data_privilege_mutations |
object[] |
Initial data grants; see shared objects for all fields. |
Result¶
{
"code": "OK",
"msg": "OK",
"data": {
"role_id": "8",
"role_version": 1,
"policy_version": 2,
"data_privilege_version": 0,
"session_invalidation_status": "not_applicable",
"idempotent_replay": false,
"provisioning_state": "ready",
"provisioning_version": 2,
"provisioning_error_code": "",
"request_id": "create-example",
"trace_id": "trace-example"
}
}
Success returns HTTP 201; only ready is the successful commit point. Do not create a successful empty shell role and append initial permissions later. If no valid permissions remain after filtering historical model_runtime.invoke, returns 422 ErrIAMRolePermissionRequired. Duplicate names return 409 ErrIAMRoleNameExists.
An already successful same-ID/same-content request returns its historical receipt; changed content conflicts. An unconfirmed original request may return 409 ErrIAMRoleWriteResultUnknown without rerunning creation. Confirmed cleanup uses ErrIAMRoleWriteRolledBack; stopped operations without confirmed full recovery use ErrIAMRoleWriteFailed. No response or a preceding 403 does not establish rollback of original creation.
Shared requests/results documents all fields, privileges, and failure-result boundaries.