Skip to content

Users

Users are the accounts in a realm — their credentials, attributes, roles, and lifecycle are managed here.

What it is

A user belongs to exactly one realm. Users sign in with username or email, and credentials are protected with Argon2id password hashing. HelixIAM enforces a configurable password policy, keeps password history to prevent reuse, and runs a HIBP breach check to reject known-compromised passwords.

Other capabilities:

  • Required actions — a framework for pending steps a user must complete at next login (e.g. update password, verify email, configure OTP).
  • Per-user roles — direct role assignments in addition to roles inherited from groups.
  • Credentials management — see, reset, and remove a user's passkeys and codes.
  • Admin impersonation — start a session as the user for support and debugging.
  • Bulk import — load many users at once.
  • GDPR — export or delete a user's personal data on request.

Note

Login accepts either username or email. Email is supported as a user attribute; make sure your subject-claim choice (see Scopes & claims) reflects how downstream apps identify users.

Watch: create a user and give them access

38 seconds, no sound. Create the user, review the admin actions, add a required action, then grant a role on the Role mappings tab. Recorded on the current release.

In the console

Users live under Manage → Users. Users are always shown by their username, never by a raw subject id. Open a user to see its tabs: Details, Role mappings, Passkeys & codes, Devices, Sessions and Linked identities.

  1. Open Manage → Users, then click Add user.
  2. Set the username and email, add any attributes, and save.
  3. On the user's Details tab, click Reset password to set a new password (subject to policy, history, and the HIBP check).
  4. Still on Details, use the Required actions section to add a step the user must complete at next login (e.g. configure OTP).
  5. On the Role mappings tab, assign realm or client roles directly — or add the user to a group that already holds them.
  6. The Passkeys & codes tab lists the user's passkeys and codes. The Devices tab lists the user's registered devices. The Linked identities tab lists accounts linked from other identity providers.
  7. Use Import users (on the Users list) to load a batch of users at once, and Impersonate (on Details) to reproduce an issue as the user. Remove user (on Details) deletes the account.
  8. Resend verification email (on Details, shown while the address is not verified) queues a new verification link; delivery is asynchronous.
  9. Sign out everywhere (on Details and on the Sessions tab, confirmed) ends every session of the user and shows what was ended.
  10. Verified attributes lists the attributes a wallet step-up kept on the profile (names, source, times) and can delete one or all of them (confirmed; audited).

Warning

Admin impersonation creates a real session as the user and is a sensitive operation. Impersonation and credential resets are recorded in the audit log — restrict who can perform them.

Citizen service numbers (BSN)

Users who signed in with DigiD have an opaque username (digid-…) and show their BSN masked, *****1234, in the list and on the details page (search matches the last four digits). Reveal full number needs the reveal-bsn permission and is recorded in the audit log. See DigiD: how the BSN is handled.

Danger

GDPR delete is irreversible and removes the user's personal data. Export first if you may need a record.

Over the API

All user management is available under /admin/realms/{realm}/users. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List users

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/users"
[
  {
    "realmId": "acme",
    "userId": "684db0eb-4afe-44f9-ad16-37a64f3496ea",
    "username": "alice",
    "email": "alice@example.com",
    "enabled": true,
    "locked": false,
    "mfaEnabled": false,
    "roles": [],
    "attributes": {},
    "createdAt": 1783339573376
  }
]

Create a user

# Refresh CSRF after any GET, then POST (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/users" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

curl -s -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"username":"alice","email":"alice@example.com","enabled":true}' \
  "$HELIX_URL/admin/realms/$REALM/users"
{
  "realmId": "acme",
  "userId": "684db0eb-4afe-44f9-ad16-37a64f3496ea",
  "username": "alice",
  "email": "alice@example.com",
  "enabled": true,
  "locked": false,
  "mfaEnabled": false,
  "roles": [],
  "attributes": {},
  "createdAt": 1783339573376
}

Set a password, assign a role, delete

Use the returned userId for subsequent calls:

# Set (or reset) the password — enforced against policy, history, and HIBP
curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"newPassword":"S3cure-passphrase!"}' \
  "$HELIX_URL/admin/realms/$REALM/users/684db0eb-4afe-44f9-ad16-37a64f3496ea/password"

# Assign a realm role (by its roleId, from GET /admin/realms/{realm}/roles)
ROLE_ID=$(curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/roles" | jq -r '.[] | select(.name == "billing-admin") | .roleId')
curl -s -b cookies.txt -X POST \
  -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d "{\"roleId\":\"$ROLE_ID\"}" \
  "$HELIX_URL/admin/realms/$REALM/users/684db0eb-4afe-44f9-ad16-37a64f3496ea/roles"

# Delete the user — returns 204 No Content
curl -s -b cookies.txt -X DELETE -H "X-XSRF-TOKEN: $CSRF" \
  "$HELIX_URL/admin/realms/$REALM/users/684db0eb-4afe-44f9-ad16-37a64f3496ea"

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /users · POST /users List / create users
GET · PUT · DELETE /users/{userId} Read / update / delete a user
POST /users/import Bulk import
GET /users/{userId}/credentials · DELETE .../credentials/{type}/{id} List / remove credentials
PUT /users/{userId}/password Set password
GET · POST /users/{userId}/roles User role mappings
GET · PUT /users/{userId}/required-actions Required actions
POST /users/{userId}/impersonate Start impersonation
POST /users/{userId}/send-verification-email Resend the verification email (429 when too many were sent)
DELETE /users/{userId}/sessions Sign the user out everywhere
GET · DELETE /users/{userId}/verified-attributes · POST .../verified-attributes/reveal Wallet-verified attributes kept on the profile (DELETE takes ?name= for one; values only with reveal-bsn)
GET /users/{userId}/gdpr/export · GET /users/{userId}/gdpr/consents · DELETE /users/{userId}/gdpr GDPR export / consents / erase

See the API reference for the complete schema of every field.

See also