# Create a role

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

```text
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

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
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:[]}')"
```

:::::
:::::{tab-item} Parameters

| 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

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "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"
  }
}
```

:::::
:::::{tab-item} Fields

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](iam-write-objects.md) documents all fields, privileges, and failure-result boundaries.

:::::
::::::
:::::::
