> For the complete documentation index, see [llms.txt](https://support.attackforge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.attackforge.com/app/modules/ai-mcp-and-skills/create-user.md).

# Create User

#### Description <a href="#description" id="description"></a>

Creates a new AttackForge user. This is a **write** operation: it persists a new user record, grants it a role, and emails the new user a welcome message.

The shape of `args` is declared inline (see Building args for Write Tools), so no preparatory call is needed. Only `username` and `email` are required; every other key has a default.

Preconditions: the caller must be an administrator, the username and email address must not already be in use, and the tenant must be within its user licence for any role other than `client`. On success the new user id is returned.

#### How To Enable <a href="#how-to-enable" id="how-to-enable"></a>

1. Go to `Users`
2. Select the user you would like to provide access to this tool
3. Click on `Access > MCP`
4. Click on `Add Tools`
5. Select the tool `create_user` and click `Add`

#### Example Prompts <a href="#example-prompts" id="example-prompts"></a>

* *Create a consultant account for Jane Smith, <jane.smith@example.com>.*
* *Add a client user for the ACME engagement and make them change their password on first login.*
* *Create a new admin user called ops.admin.*
* *Set up a user for Bob and put "Security" in the department custom field.*

#### Parameters <a href="#parameters" id="parameters"></a>

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `args`    | object | Yes      | The user-creation payload - see the keys below. |

**`args` keys:**

| Key                     | Type    | Required | Description                                                                                                                                                                                                                                                                                              |
| ----------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `username`              | string  | Yes      | The username the new user signs in with. Must not already be in use by another user.                                                                                                                                                                                                                     |
| `email`                 | string  | Yes      | Email address of the new user. Must not already be in use by another user. The welcome email is sent to this address.                                                                                                                                                                                    |
| `first_name`            | string  | No       | First name. Defaults to `New` when omitted.                                                                                                                                                                                                                                                              |
| `last_name`             | string  | No       | Last name. Defaults to `User` when omitted.                                                                                                                                                                                                                                                              |
| `role`                  | string  | No       | One of `'admin'`, `'projectoperator'`, `'librarymod'`, `'consultant'`, `'client'`. Defaults to `'client'`. Every role other than `'client'` consumes a user licence, so creating one fails once the licence is exhausted.                                                                                |
| `password`              | string  | No       | Initial password, 15 to 70 characters. It is never returned by this or any other tool, so a password set here has to reach the user by some other means. When omitted a random password is generated instead - the recommended option - and the user sets their own through the forgotten-password flow. |
| `force_password_change` | boolean | No       | Require the user to change their password the first time they sign in. Defaults to `false`.                                                                                                                                                                                                              |
| `mfa_enabled`           | boolean | No       | Require multi-factor authentication for the new user. Defaults to `true`.                                                                                                                                                                                                                                |
| `custom_fields`         | array   | No       | Custom field values, each `{ key, value }`. Discover keys via `get_field_structure(model="user")`.                                                                                                                                                                                                       |

#### Example Response

```json
{
  "user_id": "65a440c08cade68ca7bc7192"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://support.attackforge.com/app/modules/ai-mcp-and-skills/create-user.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.