Create a user
POST/user/users
Create a Moodle account with the required identity fields and optional standard profile fields. Custom profile fields will be supported in a future revision. This is not self-registration and does not create an account in an external identity provider.
Required OAuth scopes
Satisfy one set:
Required OAuth scopes:
- all of:
- core_user:user:create
Required Moodle capabilities:
- all of:
- moodle/user:create
Populating initial fields requires no additional read or update permission.
Passwords
- Password requirements depend on the selected authentication plugin and site configuration. If it uses a Moodle-managed password, supply
passwordorgeneratePassword: true, never both; otherwise, omit both. This is validated at runtime against the configured plugin. - Generated passwords require a change at first login. Email is sent after creation unless
sendPasswordEmailisfalse. - If email is suppressed, arrange access separately through password reset or credential provisioning.
- Explicit passwords must meet site policy. They are not emailed and do not require a forced password change.
- Passwords are never returned.
Creation and result
The account and standard profile fields are validated and saved atomically, applying defaults and required or unique field rules. Initial provisioning is distinct from later authentication-plugin field locks. Moodle's creation lifecycle is followed, and user_created is emitted after the supplied data is saved.
Use language for the stored language preference and timeZonePreference for the stored IANA timezone preference (null selects the server default). The computed id, fullName, profileImageUrl, profileImageUrlSmall and effective timeZone are not inputs; deleted is also excluded.
Return 201 with an {id, username} receipt and a numeric-ID resource URL in Location. No ETag is returned; an authorised GET retrieves the representation and ETag. See the 201 response for email delivery outcomes.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 422
Account and supplied fields created. For generated passwords, credentialEmailStatus is:
sent: accepted by the mail transport, not guaranteed inbox delivery.failed: delivery failed and was logged; the account still exists.notRequested: email was suppressed.
Do not repeat POST to retry email delivery. Passwords are never returned.
Response Headers
URL of the created user resource, with its numeric id.
Bad Request
Authentication is required.
The caller lacks the required token scope or Moodle capability, or the operation targets a protected account, an authentication-plugin-locked field or another non-editable field.
A username, email (where site policy requires unique addresses) or custom field violates a uniqueness rule. No creation or update is committed.
Well-formed input failed field validation: missing required, unknown or read-only fields, invalid values, policy failures or incompatible options. Permission or locked-field failures use 403; uniqueness conflicts use 409. Public recovery errors describe input only, never account existence, eligibility or delivery outcomes. Passwords and recovery tokens must not appear in errors.