Skip to content

User Management

Admins and Super Admins manage platform users through the API and (where available) the Users page in the dashboard.

User Roles

Users are assigned one of five RBAC roles. See Roles & Permissions for the full permission matrix.

Role Value Description
Super Admin super_admin Platform-wide access
Admin admin Full tenant administration
Security Analyst security_analyst Audit, anomalies, HITL
Developer developer Agent management
Viewer viewer Read-only dashboard and audit

Creating Users

curl -X POST http://localhost:8000/api/v1/users \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "analyst@acme.com",
    "password": "SecureP@ss123",
    "full_name": "Security Analyst",
    "role": "security_analyst"
  }'

Tenant scoping

Users created by an Admin are automatically assigned to the Admin's tenant. Super Admins can create users across tenants.

SSO Users

When SSO is enabled, users can also be created automatically on first IdP login (JIT provisioning). SSO users:

  • Have auth_provider and external_subject set (e.g. keycloak, Okta sub)
  • Have no local password — password reset does not apply
  • Receive roles from IdP groups (configurable via SSO_ROLE_MAPPING_JSON)

Disable auto-provisioning with SSO_AUTO_PROVISION=false to require pre-created accounts. See SSO Configuration.

Listing Users

curl "http://localhost:8000/api/v1/users?skip=0&limit=50" \
  -H "Authorization: Bearer <admin-jwt>"

Query parameters:

Parameter Type Description
skip int Pagination offset
limit int Page size (max 100)
role string Filter by role
is_active bool Filter by active status
search string Search by email or name

Updating Users

curl -X PUT http://localhost:8000/api/v1/users/<user_id> \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Senior Security Analyst",
    "is_active": true
  }'

Changing Roles

curl -X PUT http://localhost:8000/api/v1/users/<user_id>/role \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Role assignment rules

  • Admins cannot assign super_admin
  • Users cannot assign a role higher than their own
  • Super Admins can assign any role

Password Management

Reset User Password (Admin)

curl -X POST http://localhost:8000/api/v1/users/<user_id>/reset-password \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"new_password": "NewSecureP@ss456"}'

Self-Service Password Change

curl -X POST http://localhost:8000/api/v1/users/me/change-password \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "old-password",
    "new_password": "new-password"
  }'

Blocking and Unblocking

Temporarily disable a user without deleting their account:

# Block
curl -X POST http://localhost:8000/api/v1/users/<user_id>/block \
  -H "Authorization: Bearer <admin-jwt>"

# Unblock
curl -X POST http://localhost:8000/api/v1/users/<user_id>/unblock \
  -H "Authorization: Bearer <admin-jwt>"

Blocked users cannot log in. Active WebSocket connections are terminated on block.

Deleting Users

curl -X DELETE http://localhost:8000/api/v1/users/<user_id> \
  -H "Authorization: Bearer <admin-jwt>"

Irreversible

User deletion is permanent. Associated API keys are revoked. Audit logs referencing the user are retained.

API Key Management

Users can create personal API keys for SDK and CI/CD integration:

Endpoint Method Description
/api/v1/api-keys POST Create key (raw key shown once)
/api/v1/api-keys GET List user's keys (masked)
/api/v1/api-keys/{id} DELETE Revoke key

API keys are hashed with SHA-256 before storage. The raw key is never stored.

Super Admin Bootstrap

On first boot, scripts/init_super_admin.py creates the super-admin from environment variables:

Variable Default
SUPER_ADMIN_EMAIL admin@aegisai.com
SUPER_ADMIN_PASSWORD admin123

Change these immediately in production.

Audit Trail

User management actions are logged:

  • Login and logout events
  • Password changes and resets
  • Role changes
  • Block/unblock actions
  • User creation and deletion