create_user()

Creates a new user account on the ECM server. Server-assigned fields (id, guid) are populated in the returned object.

Empirically only username (XML attribute benutzer) is actually required — the server fills safe defaults for every other field. One exception: changepwd defaults to 1 server-side, forcing the new user to change their password on first login.

create_user() therefore writes changepwd="0" by default so created accounts can log in immediately. Pass change_pwd=True to opt into the forced change.

1. Signature

  • Sync

  • Async

ecm.security.create_user(
    username: str,
    *,
    login_name: str | None = None,
    display_name: str = "",
    email: str = "",
    remark: str = "",
    password: str = "",
    plain_password: bool = False,
    profile_id: int = -1,
    locked: bool = False,
    supervisor: bool = False,
    account_type: int = 0,
    flags: int = 0,
    lang_id: int = 0,
    server_id: int = 0,
    valid_from: datetime | None = None,
    valid_to: datetime | None = None,
    change_pwd: bool = False,
    never_expire: bool = False,
) -> ECMUserAttributes
await ecm.security.create_user(...) -> ECMUserAttributes

2. Parameters

Parameter Default Description

username

—

Internal user name (benutzer attribute).

login_name

username

Login credential name; defaults to username.

display_name

""

Full display name.

email

""

E-mail address.

remark

""

Optional remark.

password

""

Plaintext password. Auto-encoded into the Blue server scheme via password_encrypt() before sending — same convention as the pool client’s UserPwd parameter. Values encrypted with ECMIND_KEY are additionally decrypted via password_reveal() first.

plain_password

False

When True, password is sent without client-side encoding — the server encodes it. Requires the one-time-password feature (Login\PasswordSingleUse=1), otherwise the call fails with -1040906137.

change_pwd

False

If True, the user must change their password on first login. The server-side Login\PasswordSingleUse setting may force this regardless of the value passed here.

never_expire

False

If True, the account never expires regardless of valid_to.

profile_id

-1

-1 no profile, 0 own profile, >0 ID of an existing profile.

locked

False

Whether the account starts locked.

supervisor

False

Grant supervisor rights (XML value -1).

account_type

0

0 user, 1 app server, 2 ANONYMOUS, 3 Java app server.

flags

0

0 normal user, 1 server / ANONYMOUS.

lang_id

0

Language ID; 0 = server default.

server_id

0

Home server ID.

valid_from

None

Account valid-from timestamp.

valid_to

None

Account valid-to timestamp.

3. Return value

ECMUserAttributes with id and guid populated.

4. Errors

  • ECMException (or subclass) — when the server rejects the creation, e.g. on duplicate user name.

5. Examples

5.1. Minimal call

  • Sync

  • Async

user = ecm.security.create_user("john", display_name="John Doe", email="j@x.de")
print(user.guid, user.id)
user = await ecm.security.create_user("john", display_name="John Doe")

5.2. Time-limited account with supervisor rights

from datetime import datetime

user = ecm.security.create_user(
    "contractor1",
    display_name="External Contractor",
    email="c@partner.com",
    supervisor=True,
    valid_from=datetime(2026, 1, 1),
    valid_to=datetime(2026, 12, 31, 23, 59, 59),
)
user = ecm.security.create_user("john", password="S3cret!")
# The user can log in with "S3cret!" — encoding happens automatically.

5.4. ECMIND_KEY-encrypted password

When the ECMIND_KEY environment variable is set, the password may be passed base85+XOR-encrypted — password_reveal() decrypts it transparently before the Blue encoding step:

import os
os.environ["ECMIND_KEY"] = "shared-key"

# Assume "ENCRYPTED..." was encrypted with ECMIND_KEY:
user = ecm.security.create_user("john", password="ENCRYPTED...")

5.5. One-time password (server must be configured)

user = ecm.security.create_user(
    "john",
    password="S3cret!",
    plain_password=True,
    change_pwd=True,
)
# With plain_password=True the password is sent without client-side encoding —
# the server encodes it and the user must change it on first login.

6. See also