> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/identities/create-a-user.md).

# Create a user

Create a user record in the Webconsole on either of the two creation routes, and confirm the user has an identity and is findable in search.

## What this is, and when you need it

Creating a user writes the person's record, one or more identities, and provisioning requests to every managed system their entitlements reach. Use this when a person has to exist in OpenIAM and no authoritative feed will create them. There are **two** creation routes, and choosing the wrong one is the commonest source of "the form doesn't have the field I configured".

## At a glance

|                          |                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **You will end up with** | A user record with a user type, at least one identity, and a row in user search                                                              |
| **Where**                | **User Admin → Create New User**, `/webconsole/newUser`                                                                                      |
| **You need first**       | The `USER_ROOT_MENU` and `SAVE_USER_BTN` menu grants, the user type to create them as, and an OTP phone number if your provider does SMS OTP |
| **Takes**                | 2–5 minutes, plus however long provisioning takes to reach the managed systems                                                               |
| **Reversible**           | Partly — you can remove the user, but accounts already created on managed systems are not withdrawn                                          |

## Which of the two routes to use

Use the **classic route**, `/webconsole/newUser`, unless you have built a page template for this user type: it gives you every built-in field with no configuration. Use the **template route**, `/webconsole/new-user-template`, when a page template should supply the fields. They are compared under [the template-route variant](#variant-create-on-the-template-route).

## Create the user

{% stepper %}
{% step %}

### Open the new user form

Go to **User Admin → Create New User**, or straight to `/webconsole/newUser`.

The form loads its drop-downs from the metadata cache — user types, email types, address types, phone types, supervisor types, job codes and employee types — so a value missing from a drop-down is a missing or inactive metadata type, not a problem with this screen. Fix those at **Administration → Metadata Types** (`/webconsole/metaDataTypeSearch`).
{% endstep %}

{% step %}

### Set the user type

The **Type** list is the metadata types in the `USER_OBJECT_TYPE` grouping. The type decides which page template renders this person's form from now on, and which custom fields apply to them, so set it deliberately rather than accepting the first entry.
{% endstep %}

{% step %}

### Fill in the identity fields, including a phone if OTP requires one

`org.openiam.ui.otp.sms.phone.require.on.create` ships `true`, category `Password`, label **Require OTP Phone Number When Creating a New User?**. When it is `true` *and* the current authentication provider supports SMS OTP, a phone number of the OTP phone type is required and the save is refused without one.

`org.openiam.ui.otp.email.require.on.create` also ships `true` and does the same for an OTP email address.

**The Supervisor field accepts more than one supervisor.** Search for a user and select them to add each one; clear an entry to remove that supervisor. Opening an existing user shows the supervisors currently assigned, and saving applies the additions and removals you made together.
{% endstep %}

{% step %}

### Save

OpenIAM records the audit action `CREATE_USER` when the form was opened as a new user and `MODIFY_USER` when it was opened on an existing one, so the audit log distinguishes a creation from an edit on its own — you do not have to reconstruct which it was.

`org.openiam.send.user.activation.link` ships `true`, category `Authentication`, label **Send Activation Link to New Users**: with it on, the new user is sent an activation link instead of a password, and lands in status `PENDING_INITIAL_LOGIN`.
{% endstep %}

{% step %}

### Confirm the user has an identity

Open the new record's identities. A user with no identity on the default managed system exists but cannot sign in. If you expected identities on other managed systems, they arrive when provisioning completes, not when the save returns.
{% endstep %}
{% endstepper %}

### Variant: create on the template route

|              | Classic route                                         | Template route                                                              |
| ------------ | ----------------------------------------------------- | --------------------------------------------------------------------------- |
| Route        | `/webconsole/newUser`                                 | `/webconsole/new-user-template`                                             |
| Also serves  | `/webconsole/editUser?id=<USER_ID>`                   | `/webconsole/user-template`, `/webconsole/user-template-{extension}`        |
| The form is  | The full built-in field set, server-rendered          | The page template bound to this route's URI pattern, plus its custom fields |
| Save records | `CREATE_USER` on a new user, `MODIFY_USER` on an edit | `MODIFY_USER`, described "Save user template"                               |

The classic page offers a link across to `/webconsole/new-user-template`, so the two are easy to confuse once you have clicked through a couple of screens. Read the address bar, not the form, to tell which one you are on.

Open `/webconsole/new-user-template` with no user and no type selected and the screen shows a **select user type** step first. That is deliberate: the user type decides which page template applies, so it has to be chosen before the form can be built. Your choice is then carried in the address bar, which is what makes a type-specific creation form bookmarkable.

The form is then the page template's fields in their configured order, honouring each field's required, editable and rule settings. If a field you configured is not on the form, the template is not bound to the URI pattern this route matches — see [Build a page template](/administration-guide/identities/page-templates-and-custom-fields.md).

### Variant: create the user and its entitlements in one save

When the user's page template carries the entitlement fields — **User can select a Role**, **User can select a Group**, **User can define his organizational structure** — the form shows those lists and one save writes the profile and the entitlements together. That save audits `MODIFY_USER`, described "Save user with entitlements", and **not** `ADD_USER_TO_ROLE`, so a monitor watching only for role grants will not see it. It also treats each list shown on the form as the complete set. See [Grant and revoke access](/administration-guide/identities/grant-and-revoke-access.md).

## Verification

1. **The audit log** shows `CREATE_USER` for the save.
2. **Search finds them.** Search for the new user by employee ID at `/webconsole/users`. This is a stronger check than opening the record, because it proves the `users` index picked the person up — which the record existing does not.
3. **Identities.** One identity per managed system you expected, on the user's identities screen.
4. **Status.** `PENDING_INITIAL_LOGIN` when an activation link was sent; `ACTIVE` otherwise.

## When it goes wrong

| Symptom                                                               | Cause                                                                                                                                                                        | Fix                                                                                                        |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| The record opens correctly but user search cannot find it             | The `users` index is stale, or the record was created while the index was unavailable. Correct on its own screen and absent from search always means the index, not the data | [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md) for `users`           |
| Cannot save; validation complains about a phone number                | `org.openiam.ui.otp.sms.phone.require.on.create` is `true` and the authentication provider supports SMS OTP                                                                  | Supply a number of the OTP phone type, or change the property deliberately                                 |
| `/webconsole/new-user-template` shows a type picker instead of a form | You opened it with no user and no user type chosen. This is the designed behaviour — the type decides which template builds the form                                         | Pick the type and the form appears                                                                         |
| The template form is missing a field you configured                   | The template is not bound to this route's URI pattern                                                                                                                        | See [Build a page template](/administration-guide/identities/page-templates-and-custom-fields.md)          |
| A user type you need is not in the drop-down                          | Its metadata type is inactive, or is in a grouping other than `USER_OBJECT_TYPE`                                                                                             | Fix it at **Administration → Metadata Types**, not on this screen                                          |
| The status drop-down is disabled on your own record                   | `org.openiam.ui.webconsole.allow.change.own.status` ships `false`, and OpenIAM enables the drop-down only when that is `true` or the record is somebody else's               | Have another administrator change it. This is a guard rail, not a defect                                   |
| The user saved but has no identity anywhere                           | Provisioning did not run, or the user is entitled to nothing                                                                                                                 | Check the provisioning requests raised under the `CREATE_USER` audit event                                 |
| The user saved but never received an activation link                  | `org.openiam.send.user.activation.link` is `false`, or mail delivery failed                                                                                                  | Read the property, then [Mail and notifications](/administration-guide/platform/mail-and-notifications.md) |

## Roll it back

A user you should not have created is removed with the **Delete** action, which sets status `REMOVE` — it does not delete the record, and it may delete the person's accounts on the managed systems. See [Run a user lifecycle action](/administration-guide/identities/user-lifecycle-actions.md), which also covers what is and is not recoverable.

Accounts already created on a managed system by provisioning are **not** withdrawn by removing the OpenIAM user unless deprovisioning reaches that system. Confirm in the target, not in OpenIAM.

## Related

* [Find a user](/administration-guide/identities/find-a-user.md) — the search screen, and what to do when a user you just created is not in it
* [Build a page template](/administration-guide/identities/page-templates-and-custom-fields.md) — the fields on the template route
* [System properties](/administration-guide/reference/system-properties.md) — every property named here, with its shipped default

*Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.*


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/administration-guide/identities/create-a-user.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.