Most users are created automatically — they sign up through your application's sign-up flow, or they federate in via SSO. The admin-side create is for the rare case: an internal staff account, a service-account user, or a one-off provisioning.
Two ways to create
Section titled “Two ways to create”Invite (default)
Section titled “Invite (default)”Users → New user → Invite.
Fill in: email, optional name, optional groups. Send. The user receives an email titled "You've been invited to <tenant-name>". They click, set their own password, pass through email verification + MFA enrolment (if your policy requires either), and they're in.
Pros: the user picks their own password; no temporary credential to communicate. Cleanest path.
Direct create
Section titled “Direct create”Users → New user → Create directly.
Fill in: email, optional name, password, optional groups. Save. The user record is live immediately; the user can sign in with the email + password you set.
Toggles:
- Email verified — set to true if you've verified the email out-of-band. Skips the verification step.
- Password must be reset — set to true if the password you typed is a temporary one. User is forced to change it on first sign-in.
- Force MFA enrolment — set to true if your tenant policy is MFA-required and you want enrolment to be the first thing.
Use direct create when you can't (or don't want to) wait for the user to act on an invitation email. Typical case: provisioning a service account, or onboarding a contractor who needs immediate access.
What's required
Section titled “What's required”- Email — required. Must be unique within the tenant. Format-validated.
- Name (optional) — display name. Splits into given_name + family_name automatically if you provide "Anita Singh"; tweak manually if needed.
- Password (direct create only) — must satisfy your tenant's password policy.
- Groups (optional) — picked from existing groups. Multi-select.
- Custom attributes (optional) — any custom field your tenant defines. See Custom attributes.
What happens behind the scenes
Section titled “What happens behind the scenes”Either path produces the same shape on the user record:
- A
user_id(the platform's internal id; not editable). - An identity of kind
password(only if you set a password or the user set one via invitation). - Group memberships if you picked any.
- An audit-log entry for
user.createdwith you as the actor.
If you invited, an additional user.invited event records the invitation; the user.created event fires when they accept.
Common mistakes
Section titled “Common mistakes”- Email already exists. The form refuses with "a user with this email already exists." If the existing user is the same person, edit theirs instead of creating new. If a different person, change the email.
- Email format invalid. The platform validates RFC 5321 / 5322. Edge-case addresses (
user+tag@domain.com) work; oddities (user@localhost, missing TLD) refuse. - Password doesn't meet policy. The error names the rule that failed (length, character classes). Adjust and retry.
- Group not found. If the group was renamed or deleted between you starting the form and submitting, the submit fails. Refresh + retry.
What to do next
Section titled “What to do next”After creating, open the user's detail page to:
- Add MFA factors (rare; usually the user enrols their own).
- Assign roles / refine groups.
- Set custom attributes.
- Check the audit summary to confirm the create looks right.
For bulk creation (more than ~10 users at a time), see Bulk import.