Users

Users

Manage user accounts, authentication, and role assignments in Mantis.

Overview

User Model

Field	Type	Description
id	UUID	Unique identifier
email	String	Email address (unique)
username	String	Display username (unique)
password_hash	String	Argon2id hash (local auth only)
display_name	String	Optional display name
status	Enum	active, inactive, locked, pending
email_verified	Boolean	Email verification status
tenant_id	UUID	Optional tenant scope
last_login_at	DateTime	Last successful login
created_at	DateTime	Account creation time
updated_at	DateTime	Last update time (nullable)

User Status

Status	Description
active	Account is active and can log in
inactive	Account is inactive (disabled by admin)
locked	Account is locked (too many failed logins)
pending	Account is pending verification

API Operations

List Users

curl -X GET \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/admin/users?page=1&limit=20"

Response:

{
  "data": [
    {
      "id": "019b937d-4862-8e07-ac3a-1b8589d1b807",
      "email": "alice@example.com",
      "username": "alice",
      "display_name": "Alice Smith",
      "status": "active",
      "email_verified": true,
      "role_count": 2,
      "tenant_id": null,
      "last_login_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T08:00:00Z"
    }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "limit": 20,
    "total_pages": 3
  }
}

Get User Details

curl -X GET \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID"

Response includes roles, permissions, and external identities:

{
  "id": "019b937d-4862-8e07-ac3a-1b8589d1b807",
  "email": "alice@example.com",
  "username": "alice",
  "display_name": "Alice Smith",
  "status": "active",
  "email_verified": true,
  "roles": [
    {
      "id": "019b937d-4862-84ae-9c2a-6ac230cc4c7e",
      "name": "operator",
      "description": "Can manage deployments and targets",
      "is_system": true
    }
  ],
  "permissions": [
    "deployments:create",
    "deployments:read",
    "targets:create",
    "targets:read"
  ],
  "tenant_id": null,
  "tenant_name": null,
  "external_identities": [
    {
      "provider_id": "019b937d-4862-8def-4567-001122334455",
      "provider_name": "Okta",
      "external_username": "alice.smith",
      "external_email": "alice.smith@company.com",
      "last_login_at": "2024-01-15T10:30:00Z"
    }
  ],
  "last_login_at": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T08:00:00Z",
  "updated_at": "2024-01-10T14:00:00Z"
}

Create User

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "email": "bob@example.com",
        "username": "bob",
        "password": "SecurePassword123!",
        "display_name": "Bob Jones",
        "tenant_id": null,
        "role_ids": ["019b937d-4862-84ae-9c2a-6ac230cc4c7e"]
    }' \
    "https://api.mantis.local/api/v1/admin/users"

Update User

curl -X PUT \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "display_name": "Alice S.",
        "status": "active",
        "email_verified": true
    }' \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID"

Delete User

curl -X DELETE \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID"

Caution

Users cannot delete their own account. Another admin must perform this action.

Reset Password

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "new_password": "NewSecurePassword456!"
    }' \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID/password"

Role Management

List User Roles

curl -X GET \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID/roles"

Assign Roles

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "role_ids": ["role_abc", "role_def"]
    }' \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID/roles"

Remove Roles

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "role_ids": ["role_abc"]
    }' \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID/roles/remove"

User Provisioning

Local Users

Create users directly with local credentials:

SSO/OIDC Users

Users can be provisioned automatically on first SSO login, provided the identity provider is scoped to a tenant and has auto-provisioning enabled (auto_create_users). System-wide (global) identity providers do not auto-provision new users (SEC-OIDC-02); link the provider to a tenant to enable this:

Tenant Assignment

Assigning Users to Tenants

curl -X PUT \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "tenant_id": "tenant_xyz789"
    }' \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID"

Removing Tenant Assignment

Set tenant_id to null to make user global:

curl -X PUT \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "tenant_id": null
    }' \
    "https://api.mantis.local/api/v1/admin/users/$USER_ID"

Password Policy

Requirements

Password requirements are hardcoded and cannot be changed via configuration:

• Minimum 12 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one digit
• At least one special character (!@#$%^&*()_+-=[]{}|;:,.<>?)

Password Storage

• Passwords hashed with Argon2id (library default parameters)
• Original passwords never stored
• Hash comparison for authentication

External Identities

Linked Accounts

Users can have multiple external identities:

Field	Description
provider_id	Identity provider reference
provider_name	Name of the identity provider
external_username	Username from external provider
external_email	Email from external provider
last_login_at	Last SSO login via this provider

Identity Linking

When a user logs in via SSO:

1. System checks for existing external_identity match
2. If found, updates last login and uses linked user
3. If not found, creates new user or links to existing by email

Unlink External Identity

# Via admin UI or direct database operation
DELETE FROM external_identities
WHERE user_id = $USER_ID
AND provider_id = $PROVIDER_ID;

Audit Trail

All user operations are logged:

Event	Category	Severity
user.created	user_management	Info
user.updated	user_management	Info
user.deleted	user_management	Info
user.password_reset	user_management	Security
user.roles_assigned	authorization	Security
user.roles_removed	authorization	Security

Example audit entry:

{
  "event": "user.created",
  "category": "user_management",
  "actor": {
    "user_id": "019b937d-4862-8e07-ac3a-1b8589d1b801",
    "username": "admin"
  },
  "resource": {
    "type": "user",
    "id": "019b937d-4862-8e07-ac3a-1b8589d1b809"
  },
  "metadata": {
    "username": "newuser",
    "email": "newuser@example.com",
    "roles": ["019b937d-4862-84ae-9c2a-6ac230cc4c7e"]
  },
  "outcome": "success"
}

Best Practices

User Onboarding

1. Use SSO when possible - Reduces password management overhead
2. Assign minimum required roles - Follow least privilege principle
3. Set tenant scope appropriately - Limit access to necessary resources
4. Verify email addresses - Ensure contact information is accurate

User Offboarding

1. Set status to inactive - Immediate access revocation
2. Remove role assignments - Clear all permissions
3. Review owned resources - Transfer ownership if needed
4. Delete account - After transition period

Regular Audits

• Review active users quarterly
• Verify role assignments match current responsibilities
• Check for unused accounts (no recent login)
• Audit external identity links

Troubleshooting

User Cannot Login

1. Check account status:

   SELECT status FROM users WHERE email = 'user@example.com';

2. Verify password (local auth):

   • Reset password via admin API
   • Check for caps lock / keyboard issues

3. Check external identity (SSO):

   • Verify provider is configured
   • Check role mappings exist
   • Review IdP logs for errors

User Missing Permissions

1. List user’s current roles:

   curl -s -H "Authorization: Bearer $TOKEN" \
       https://api.mantis.local/api/v1/admin/users/$USER_ID/roles

2. Check role permissions:

   curl -s -H "Authorization: Bearer $TOKEN" \
       https://api.mantis.local/api/v1/admin/roles/$ROLE_ID/permissions

3. Assign missing role:

   curl -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"role_ids": ["role_xyz"]}' \
       https://api.mantis.local/api/v1/admin/users/$USER_ID/roles

Next Steps

• Roles - Role configuration
• Permissions - Permission reference
• Identity Providers - SSO setup