Managing Users

Creating users

Admin UI

Go to Admin UI → Users → New User. Fill in username, password, and optionally email and role.

API

curl -X POST https://auth.example.com/admin/api/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "secure-password",
    "email": "[email protected]",
    "role": "user"
  }'

The role must be user or admin. Omitting it or sending an empty string creates a regular user. Only an authenticated administrator can create users through this endpoint, including new administrators.

Listing users

curl https://auth.example.com/admin/api/users \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Returns a paginated list of user objects (without password hashes or TOTP secrets).

Updating a user

curl -X PUT https://auth.example.com/admin/api/users/USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "admin"
  }'

All fields are optional in the update request — only provided fields are changed.

Updatable fields: username, password, email, role, is_email_verified, totp_verified.

Resetting MFA

To force a user to re-enroll TOTP (e.g. they lost their authenticator app):

curl -X PUT https://auth.example.com/admin/api/users/USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"totp_verified": false}'

On their next login, they will be shown the TOTP enrollment QR code again.

Unlocking a locked account

If a user is locked out after too many failed attempts:

curl -X POST https://auth.example.com/admin/api/users/USER_ID/unlock \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Or via Admin UI → Users → (user) → Unlock.

Deleting users

curl -X DELETE https://auth.example.com/admin/api/users/USER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

This permanently removes the user and their associated data (sessions, tokens, passkeys, trusted devices).

Keeping administrator access

Autentico rejects demoting, deactivating or deleting the last active administrator with 409 Conflict and error last_active_admin. Create or promote another active administrator first. Deactivated administrators do not count as replacements. Profile updates that preserve the admin role remain available.

The same protection applies to immediate self-service deletion and approval of deletion requests. Rejected actions leave the account, sessions and pending deletion request intact. Concurrent removals are checked in the same database transaction as each change.