# Create a user

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

Invite a user to the current workspace. Each invitation can use only one identity: an email address, mobile number, or GitHub login. The user might not be manageable until the invitation is accepted.

```text
POST https://moi.matrixorigin.cn/newmoi/user/create
```

## Preparation before calling

Decide how to invite the user and prepare one identity for the invitee. For invitations by email or mobile number, first [select roles](../roles/list-roles.md#select-a-role) to determine the assigned roles and default role. For invitations by GitHub login with no role assignment, selecting roles beforehand is not required.

Prepare a [personal access token](../../../../../guides/genesis/api-keys.md#manage-api-keys) and [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-a-workspace-id) with the required permissions for the target workspace.

## Request parameters

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

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/user/create" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data_analyst",
    "email": "analyst@example.com",
    "role_id_list": [1001],
    "default_role_id": 1001,
    "tag_list": []
  }'
```

:::::
:::::{tab-item} Parameter description

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | User name in the current workspace; maximum 255 characters. |
| `email` | string | Conditionally | Invitation email address; provide exactly one of `email`, `mobile_number`, and `github_login`. |
| `mobile_number` | string | Conditionally | An 11-digit mainland China mobile number; provide exactly one of `mobile_number`, `email`, and `github_login`. |
| `github_login` | string | Conditionally | GitHub login; provide exactly one of `github_login`, `email`, and `mobile_number`. |
| `description` | string | No | User description. |
| `default_role_id` | integer | Conditionally | Default role ID. When a role list is provided, it must be in `role_id_list`. |
| `password` | string | No | Compatibility password field. |
| `role_id_list` | integer (array) | Conditionally | Initial list of role IDs. It cannot be empty for invitations by email or mobile number. |
| `tag_list` | object (array) | No | Initial user tags. Each item contains `id` and `value`. |
| `tag_list[].id` | integer | Yes | Tag ID. |
| `tag_list[].value` | string | Yes | Tag value. |

GitHub invitations can be submitted without assigning roles. In that case, submit an empty `role_id_list` and set `default_role_id` to `0`. If roles are assigned with a GitHub invitation, the default role must still be included in the role list.

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

## Successful response

A successful response means that the invitation request was processed; it does not mean that the user is already an active workspace member. Invitations by email, mobile number, or a GitHub login that resolves to an account return the target user ID. When a GitHub login is not yet associated with an account, the service saves a pending invitation and returns an empty ID.

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "iam-user-001"
  }
}
```

:::::
:::::{tab-item} Field details

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.id` | string | IAM user ID for the invitation target. It is an empty string when a pending GitHub invitation is not yet associated with an account. |

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

## Error response

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

```json
{
  "code": "INVALID_ARGUMENT",
  "msg": "请求参数无效",
  "data": null
}
```

:::::
:::::{tab-item} Field details

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

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

## Next steps

[Confirm the invitation status](list-users.md#confirm-the-invitation-status) in the same workspace, then decide whether to continue managing the user.