User administration

The Users administration page is at /admin/users. API access requires the admin role; normal users cannot manage server accounts.

Local users

When local login is enabled, administrators can create users with username, optional email, password and role. Usernames contain 1–150 characters from letters, digits, ., _, @ and -. Passwords accepted by the API contain 8–256 characters.

Set a password for accounts expected to use local sign-in. Creating an account without one does not automatically link it to an identity provider.

SSO users

SSO accounts are normally created at first accepted login. Their email and password are managed by the identity provider. The Users API refuses administrator attempts to change those fields for SSO users. If admin groups are configured, the role is managed by SSO too and cannot be changed here.

Disabling a Zukan account blocks access and ends its sessions. The identity provider's account lifecycle remains separate.

Roles and isolation

Capability	User	Administrator
Browse imported catalogs	Yes	Yes
Manage own collection and preferences	Yes	Yes
Use scan identification	Yes	Yes
Manage accounts	No	Yes
Queue syncs and edit schedules	No	Yes
Resolve source differences and refresh stale cards	No	Yes
Use the app during automatic maintenance	No, except auth routes	Yes

The ordinary collection API always scopes results to the signed-in account. Administrator role is not a documented “view anyone's collection” UI. Operators with direct database/host access are outside that application-level separation.

Password reset and disabling

A local password reset or disabling an account increments its authentication version and revokes refresh sessions, ending existing access. Role changes are read from the database during authenticated requests. An administrator cannot demote or disable their own account through this API.

Delete an account

Deleting a user is permanent and cascades to the user's collection items, stock transactions and identity/session records according to the database relationships. The API prevents an administrator from deleting themselves. There is no normal product recovery bin; restore from a suitable server backup if recovery is necessary.

CLI recovery

docker compose exec api zukan create-admin recovery-admin

The CLI prompts for the new password. If the username already exists, it resets that account, enables it, grants administrator role and ends prior sessions. Choose the target username carefully; this is not a read-only inspection command.

Bootstrap environment variables apply only when the database contains no users. They do not repair an existing admin account.

Implementation references

• backend/app/api/users.py
• backend/app/cli.py
• backend/app/api/deps.py