User Management

User management lives on the dashboard Users page (/users), and permission depends on the action: read admin:user:read, create admin:user:create, update/activate/deactivate/password policy admin:user:update, delete admin:user:delete. The built-in Admin role holds all four.

This page lists the real endpoint for every action, its validation rules, and what failure looks like. How user roles affect permissions is covered in Roles & Permissions.

Listing and Filtering

GET /api/v1/admin/users (admin:user:read) returns a paginated user list with these parameters:

Status semantics: active = is_active=true; inactive = is_active=false with approval_status=approved; pending = awaiting approval (approval_status=pending, is_active=false).

The header stats come from GET /api/v1/admin/users/stats (admin:user:read), returning total / active / inactive / pending. The list deliberately does not expose login count, failed-login count, or last password change — the API omits those fields.

Creating Users

POST /api/v1/admin/users (admin:user:create):

1. Click Create User.
2. Fill in Username (globally unique), Email (globally unique, must be a valid address), Password, and the Active switch (is_active).
3. Save.

Backend behaviour and validation:

Bulk Import / SSO Provisioning

Not implemented / Roadmap. There is no CSV/JSON/Excel user import; users are created one at a time (POST /api/v1/admin/users) or auto-provisioned on first SSO login.

SSO provisioning is driven by site settings (Site Settings → SSO/Security):

Not implemented / Roadmap: SSO provisioning has no email-domain allowlist.

Viewing User Details

Click a user to open the detail/edit panel (GET /api/v1/admin/users/{user_id}, admin:user:read). Available fields:

• Identity: username, email, is_active, approval_status, is_superuser, auth_source (local / sso), email_verified
• Preferences: locale, avatar_url
• Timestamps: created_at, last_login
• Password state: force_password_change, password_expiration_exempt (rendered as a password-status badge in the list)
• Authorization: roles (array of global roles)
• SSO: sso_connections (provider, external account, first/last login); disconnect is available with admin:sso:update

Not implemented / Roadmap: there is no per-user activity view, login history, active-session list, or session revocation inside user management. Account lockout is enforced by the global login policy max_login_attempts / lockout_duration_minutes; review user actions in Audit Logs filtered by user.

Editing Users

PUT /api/v1/admin/users/{user_id} (admin:user:update). Submittable fields:

Role Change Protection Rule

roles replaces the set (clear first, then write — omitted roles are lost; unmatched names are ignored). If the target is still owner/admin of some team and the new role set no longer contains team:manage (or *), the request fails with 403 operation_not_permitted (permission: team:manage). Downgrade their team role first, then strip the global role — the reverse order is blocked.

Submitting a password sends the user a user.password_reset notification.

Account Status

What deactivation actually does:

• No sign-in: both JWT and API-key authentication reject an is_active=false user (401 inactive_user; a pending user gets pending_approval_user).
• Integrations using that user's API keys fail immediately — the key record is untouched, but authentication rejects it because the user is inactive.
• Resources, team memberships, and conversations are all preserved; reactivating restores access.

Both actions send the user a user.activated / user.deactivated notification and write an audit entry (activate_user / deactivate_user).

Deleting Users

DELETE /api/v1/admin/users/{user_id} (admin:user:delete). The only hard block: an is_superuser=true account returns cannot_delete_superuser. The frontend delete dialog requires typing the username to confirm and lists the impact.

Deletion impact (per model FK rules, verified in models/*.py):

Passwords and Password Expiration

There is no "reset to a temporary password" or "send a reset email from the admin panel" flow. Administrators combine these per-user operations with the global password policy:

The frontend exposes these in the detail panel and the row menu, and only when auth_source=local (SSO users have no local password); the global policy is configured in Site Settings → Security.

TOTP (2FA)

Users enable, disable, and regenerate backup codes themselves in personal settings (see Sign-in & Accounts).

# Requires a superuser token
curl "https://your-domain.com/api/v1/admin/totp/users/$USER_ID/status" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

curl -X POST "https://your-domain.com/api/v1/admin/totp/users/$USER_ID/disable" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Bulk Operations

Selecting several users opens a floating toolbar at the bottom. Note that several of these are frontend loops over the single-user endpoint — there is no matching bulk endpoint:

Because most loops have no server-side batch, one failure does not roll back the others; the toast count may not match the actual number of successes, so re-check users whose permissions/state conflicted before retrying.

Not implemented / Roadmap: no bulk add/remove from teams, no bulk export, no CSV import/export.

Sending Email

POST /api/v1/admin/users/send-email with body {"user_ids": [...], "subject": "...", "content": "..."}, requires admin:user:update. The response is {"sent_count": n, "skipped_count": n, "total": n}.

Limits (exceeding them fails the request; there is no partial send):

User Roles

Global roles (multi-select, roles) determine system-level and dashboard capability, while team roles determine in-team level. The 5 built-in roles and their permission sets are in Roles & Permissions:

Team roles (owner/admin/member/viewer) are maintained on the teams pages, not in the user detail: the user detail only displays team membership.

Best Practices

✅ Do:

• Review the user list regularly and deactivate leavers promptly (deactivation blocks sign-in and API keys immediately)
• Assign the minimal necessary global role right after creation
• Require 2FA for privileged accounts and keep a normal rotation policy rather than relying on password_expiration_exempt
• Work through the expiring-passwords list ahead of expiry instead of firefighting lockouts
• Leave a trail around deactivate/delete/role changes (audit logging does this automatically)

❌ Don't:

• Share an administrator account (audit logs can no longer attribute actions)
• Delete a team owner's account directly (the team becomes ownerless)
• Replace a role set with PUT /admin/users/{id} and forget a role
• Rely on hidden frontend buttons for access control — the endpoint validates independently

Troubleshooting

Cannot Create a User

1. Check whether the username or email is already taken (user_with_username_exists / user_with_email_exists).
2. Check the email format is valid.
3. Check that the caller holds admin:user:create.

A User Cannot Sign In

1. Verify is_active=true (deactivated or pending users get 401).
2. Verify the password; if needed, force a change or set a new password first.
3. Verify the account is not locked by the login policy (max_login_attempts / lockout_duration_minutes).
4. Check TOTP state; if the user lost their authenticator, a superuser disables TOTP through the API (no UI).
5. Investigate suspicious sign-ins in Audit Logs filtered by user.

Cannot Delete a User

• The target is a superuser → cannot_delete_superuser (remove the superuser flag first, or deactivate instead).
• The target owns a team → the backend does not block the deletion, but the team loses its owner; transfer ownership inside the team first.
• Everything else deletes successfully, so double-check the cascade list above (conversations, API keys, and memberships disappear with the account).

Role Change Returns 403

The user is still owner/admin of some team while the new role set lacks team:manage. Downgrade their team membership role first, then change the global roles.

API Endpoint Reference

See also:

• Sign-in & Accounts — password policies, TOTP, and account recovery
• Roles & Permissions — global roles, permission codes, and 403 troubleshooting
• Teams & Members — in-team member roles and ownership transfer