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.

Last updated on