Skip to content

User Account Management

Jump to bottom
Andrew den Hertog edited this page Dec 3, 2025 · 1 revision

User Account Management

This guide covers creating, managing, and deleting user accounts in Codex Web.

Table of Contents

Creating User Accounts

Prerequisites

Before creating a user account:

  • ✅ You must be a Platform Admin
  • ✅ Have the user's email address
  • ✅ Know which group(s) they should belong to
  • ✅ Cognito or Google OAuth configured

Creation Methods

Via Admin UI

  1. Navigate to Admin Panel:

    • Log in to Codex Web
    • Click profile menu → Admin Panel
    • Go to Users section

  2. Click "Create User" Button

  3. Fill in User Information:

    Email (required)

    • User's email address
    • Must be unique in the system
    • Will be used for authentication
    • Format: user@example.com

    Name (optional, recommended)

    • User's full name or display name
    • Shown in UI and logs
    • Example: "John Smith"

    Username (optional)

    • Auto-generated from email if not provided
    • Can be customized
    • Must be unique

    Temporary Password (optional)

    • Initial password for the user
    • If blank, user receives password reset email
    • Must meet auth provider requirements

    Send Invite (checkbox)

    • ✅ Checked: User receives welcome email
    • ❌ Unchecked: User created without notification

    Is Admin (checkbox)

    • ✅ Checked: User gets Platform Admin privileges
    • ❌ Unchecked: Regular user

    Groups (multi-select)

    • Select one or more groups
    • User can access workspaces in these groups
    • Can be empty (user won't have workspace access)
    • Can add more groups later

  4. Click "Create User"

  5. Note the User ID:

    • System generates unique user ID
    • Format: usr_abc123...
    • Save for reference

Via API

# Set your auth token
export TOKEN="your-jwt-token"
export API_URL="https://your-codex.com/api"

# Create user
curl -X POST "${API_URL}/admin/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "temporaryPassword": "TempPass123!",
    "sendInvite": true,
    "isAdmin": false,
    "groups": ["grp_abc123", "grp_xyz789"]
  }'

Response:

{
  "id": "usr_def456",
  "username": "newuser",
  "email": "newuser@example.com",
  "name": "New User",
  "groups": ["grp_abc123", "grp_xyz789"],
  "groupMemberships": [
    {"groupId": "grp_abc123", "role": "member"},
    {"groupId": "grp_xyz789", "role": "member"}
  ],
  "isAdmin": false,
  "createdAt": "2024-12-03T10:00:00Z"
}

What Happens During Creation

  1. Validation:

    • Email uniqueness check
    • Group existence verification
    • Input validation

  2. Cognito User Creation (if enabled):

    • User created in Cognito User Pool
    • Email verified (or verification sent)
    • Password set (temporary or generated)
    • User added to groups if admin

  3. Database Record:

    • User record created in DynamoDB
    • Unique user ID generated
    • Group memberships stored
    • Admin status recorded

  4. Audit Log:

    • Admin action logged
    • Includes who created the user
    • Records timestamp
    • Stores user details

  5. Notification (if enabled):

    • Welcome email sent
    • Contains login instructions
    • Includes temporary password (if set)
    • Links to platform

Post-Creation Steps

Verify Creation:

  1. Check user appears in user list
  2. Verify group memberships
  3. Confirm role assignments
  4. Test user can log in

Communicate with User:

  • Send login URL
  • Provide temporary password (if used)
  • Explain first steps
  • Link to user documentation

Documentation:

  • Record user creation in your system
  • Note which groups assigned
  • Document any special access
  • Update team rosters

Managing Existing Users

Viewing User Details

Find a User

Via Admin UI:

  1. Go to Admin Panel → Users
  2. Search by:
    • Email
    • Name
    • Username
  3. Click user to view details

Via API:

# Get specific user
curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/admin/users/{userId}"

# Search users
curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/admin/users?search=john"

User Information Display

Basic Information:

  • User ID
  • Username
  • Email
  • Name
  • Creation date
  • Last login date

Access Information:

  • Groups the user belongs to
  • Role in each group (member/admin)
  • Platform admin status
  • Total workspace count

Activity:

  • Number of workspaces
  • Last workspace accessed
  • Recent activity

Updating User Information

Update Name or Email

Via Admin UI:

  1. Navigate to user details
  2. Click Edit button
  3. Update name or email
  4. Click Save

Via API:

curl -X PATCH "${API_URL}/admin/users/{userId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "email": "newemail@example.com"
  }'

Important:

  • Email changes may require re-verification
  • Cognito user is updated automatically
  • Old email may receive notification
  • Audit log records the change

Managing Group Membership

Add User to Group:

Via UI:

  1. Go to user details
  2. Click Add to Group
  3. Select group
  4. Choose role (member/admin)
  5. Click Add

Via API:

curl -X POST "${API_URL}/admin/users/{userId}/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "grp_abc123",
    "role": "member"
  }'

Remove User from Group:

Via UI:

  1. Go to user details
  2. Find group in memberships list
  3. Click Remove button
  4. Confirm removal

Via API:

curl -X DELETE "${API_URL}/admin/users/{userId}/groups/{groupId}" \
  -H "Authorization: Bearer $TOKEN"

Change Role in Group:

Via API:

curl -X PATCH "${API_URL}/admin/users/{userId}/groups/{groupId}/role" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Note: User must not have active workspaces in a group before removal.

User Roles and Permissions

Platform Admin Status

Promoting to Platform Admin:

Via UI:

  1. Go to user details
  2. Click Promote to Admin
  3. Confirm the action

Via API:

curl -X POST "${API_URL}/admin/users/{userId}/promote" \
  -H "Authorization: Bearer $TOKEN"

What Changes:

  • isAdmin flag set to true
  • User added to admin group in Cognito (if enabled)
  • User gains full platform access
  • Can access admin panel
  • Can manage all users and groups

Demoting from Platform Admin:

Via UI:

  1. Go to user details
  2. Click Demote from Admin
  3. Confirm the action

Via API:

curl -X POST "${API_URL}/admin/users/{userId}/demote" \
  -H "Authorization: Bearer $TOKEN"

Restrictions:

  • ❌ Cannot demote yourself
  • ⚠️ Ensure at least one other admin exists
  • ✅ User retains group memberships
  • ✅ Existing workspaces unaffected

Group Admin Status

Promoting to Group Admin:

Via API:

curl -X POST "${API_URL}/admin/users/{userId}/groups/{groupId}/promote" \
  -H "Authorization: Bearer $TOKEN"

Effect:

  • User's role in that group becomes "admin"
  • Can manage all workspaces in the group
  • Cannot add/remove group members
  • Still not a Platform Admin

Demoting from Group Admin:

Via API:

curl -X POST "${API_URL}/admin/users/{userId}/groups/{groupId}/demote" \
  -H "Authorization: Bearer $TOKEN"

Effect:

  • User's role in that group becomes "member"
  • Can only manage own workspaces
  • Loses group admin privileges

Permission Matrix

See Privilege Guidelines for complete permission details.

Password Management

Password Policies

Requirements (enforced by auth provider):

  • Minimum 8 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one number
  • At least one special character

Best Practices:

  • Use temporary passwords for new users
  • Force password change on first login
  • Enable MFA when possible
  • Rotate credentials regularly

Resetting User Passwords

Via Admin UI:

  1. Go to user details
  2. Click Reset Password
  3. Enter new temporary password
  4. Choose "Permanent" or "Temporary"
    • Temporary: User must change on next login
    • Permanent: Password is kept
  5. Click Reset

Via API:

curl -X POST "${API_URL}/admin/users/{userId}/reset-password" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "newPassword": "TempPass123!",
    "permanent": false
  }'

What Happens:

  • Password set in Cognito
  • User notified (if configured)
  • Must use new password to log in
  • Audit log records admin action

Note: This only works when Cognito is configured. For Google OAuth, users must reset via Google.

Password Reset Workflow

User-Initiated Reset:

  1. User clicks "Forgot Password" on login
  2. Redirected to auth provider
  3. Receives reset email
  4. Sets new password
  5. Can log in with new password

Admin-Initiated Reset:

  1. Admin sets temporary password
  2. Admin communicates password to user securely
  3. User logs in with temporary password
  4. User forced to change password
  5. User sets permanent password

Account Status Control

Disabling User Accounts

When to Disable:

  • Temporary leave of absence
  • Security investigation
  • Policy violation (temporary)
  • Account review pending

How to Disable:

Via UI:

  1. Go to user details
  2. Click Disable Account
  3. Confirm action

Via API:

curl -X POST "${API_URL}/admin/users/{userId}/disable" \
  -H "Authorization: Bearer $TOKEN"

Effect:

  • User cannot log in
  • Active sessions terminated
  • Workspaces remain but inaccessible
  • Group memberships retained
  • Database record unchanged

Restrictions:

  • ❌ Cannot disable yourself

Enabling User Accounts

How to Enable:

Via UI:

  1. Go to user details
  2. Click Enable Account
  3. Confirm action

Via API:

curl -X POST "${API_URL}/admin/users/{userId}/enable" \
  -H "Authorization: Bearer $TOKEN"

Effect:

  • User can log in again
  • All access restored
  • Workspaces accessible
  • No data loss

Account States

State Can Log In Can Access Workspaces Can Be Modified
Active ✅ Yes ✅ Yes ✅ Yes
Disabled ❌ No ❌ No ✅ Yes
Deleted ❌ No ❌ No ❌ No

User Deletion

Before Deleting a User

⚠️ WARNING: User deletion is permanent!

Pre-Deletion Checklist:

  1. ✅ Confirm user should be deleted
  2. ✅ Check if user has workspaces
  3. ✅ Decide what to do with workspaces
  4. ✅ Notify stakeholders
  5. ✅ Document the deletion
  6. ✅ Have manager/HR approval (if required)

Workspace Handling:

Option A: Delete workspaces

  • All user's workspaces deleted
  • All workspace data lost
  • Resources freed immediately

Option B: Transfer workspaces (manual process)

  • Admin manually re-assigns workspaces
  • Update workspace ownership in database
  • Preserve data for team

Option C: Backup then delete

  • Export important workspace data
  • Document workspace configurations
  • Then delete workspaces

Deletion Process

Via Admin UI:

  1. Go to user details
  2. Check workspace count
  3. Click Delete User
  4. Warning dialog appears: 
    Delete User: user@example.com?

This user has 3 workspace(s).
Deleting the user will NOT delete workspaces.

Are you sure?
[Cancel] [Delete User]
  5. Confirm deletion

Via API:

curl -X DELETE "${API_URL}/admin/users/{userId}" \
  -H "Authorization: Bearer $TOKEN"

What Happens During Deletion

  1. Validation:

    • Check if user exists
    • Verify you're not deleting yourself
    • Confirm admin privileges

  2. Workspace Check:

    • Count user's workspaces
    • Log warning if workspaces exist
    • Workspaces remain but orphaned

  3. Cognito Deletion (if enabled):

    • User deleted from Cognito
    • Cannot log in anymore
    • Email freed for re-use

  4. Database Deletion:

    • User record removed from DynamoDB
    • Group memberships cleared
    • User ID freed

  5. Audit Log:

    • Deletion recorded
    • Includes admin who deleted
    • Records timestamp
    • Notes deleted user email

Post-Deletion

Immediate Effects:

  • User cannot log in
  • User removed from all groups
  • Email can be reused for new account
  • User ID can be reused

Workspace Orphaning:

  • Workspaces still exist
  • userId field still set
  • User doesn't appear in UI
  • Platform admin can still delete workspaces

Cleanup Orphaned Workspaces:

# List all workspaces for deleted user
curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/admin/workspaces" | jq '.[] | select(.userId == "usr_deleted")'

# Delete each workspace
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/admin/workspaces/{workspaceId}"

Recovery

User deletion is irreversible!

If deleted by mistake:

  1. Create new user with same email
  2. New user ID will be different
  3. Cannot restore old workspaces to new user
  4. Must manually transfer data

Prevention:

  • Always double-check before deleting
  • Use disable instead when unsure
  • Have a second admin review
  • Document deletion reason

Bulk Operations

Bulk User Creation

Via CSV Upload (if implemented):

  1. Prepare CSV file: 
    email,name,groups,isAdmin
user1@example.com,User One,grp_abc123,false
user2@example.com,User Two,grp_abc123;grp_xyz789,false
  2. Upload via admin UI
  3. Review preview
  4. Confirm creation

Via Script:

#!/bin/bash
# bulk_create_users.sh

TOKEN="your-jwt-token"
API_URL="https://your-codex.com/api"

while IFS=',' read -r email name groups isAdmin; do
  curl -X POST "${API_URL}/admin/users" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"email\": \"$email\",
      \"name\": \"$name\",
      \"groups\": [\"$groups\"],
      \"isAdmin\": $isAdmin,
      \"sendInvite\": true
    }"
  echo "Created $email"
  sleep 1  # Rate limiting
done < users.csv

Bulk Group Assignment

Add Multiple Users to Group:

#!/bin/bash
# bulk_add_to_group.sh

TOKEN="your-jwt-token"
API_URL="https://your-codex.com/api"
GROUP_ID="grp_abc123"

for USER_ID in usr_001 usr_002 usr_003; do
  curl -X POST "${API_URL}/admin/users/${USER_ID}/groups" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"groupId\": \"$GROUP_ID\", \"role\": \"member\"}"
  echo "Added $USER_ID to $GROUP_ID"
done

Bulk User Export

Export All Users:

curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/admin/users?limit=1000" > all_users.json

# Convert to CSV
jq -r '.items[] | [.id, .email, .name, .isAdmin, .createdAt] | @csv' \
  all_users.json > users.csv

Best Practices

User Creation

Onboarding:

  • Create accounts before user's start date
  • Send welcome email with instructions
  • Assign to appropriate groups immediately
  • Set temporary password
  • Include link to documentation

Naming:

  • Use real names when possible
  • Consistent format (e.g., "First Last")
  • Avoid special characters
  • Use corporate email

Access Management

Principle of Least Privilege:

  • Start with minimal access
  • Add groups as needed
  • Review permissions regularly
  • Remove unnecessary access

Group Assignment:

  • Assign users to groups at creation
  • Document group purposes
  • Don't create users without groups
  • Review memberships quarterly

Admin Privileges:

  • Minimize number of platform admins
  • Document why user needs admin
  • Use group admin where possible
  • Review admin list monthly

Security

Password Security:

  • Always use temporary passwords
  • Force change on first login
  • Never share passwords
  • Use strong passwords

Account Reviews:

  • Quarterly access reviews
  • Disable inactive accounts
  • Remove departed users promptly
  • Audit admin accounts monthly

Audit Logging:

  • Review admin actions weekly
  • Investigate anomalies
  • Document all deletions
  • Maintain log retention

Communication

User Communication:

  • Welcome email for new users
  • Notice before disabling
  • Explanation for deletions
  • Documentation links

Documentation:

  • Record all admin actions
  • Note special circumstances
  • Update team rosters
  • Maintain user database

Troubleshooting

User Creation Fails

Error: "Email already exists"

  • Check if user already in system
  • Search by email
  • Delete old user or use different email
  • Check Cognito user pool

Error: "Group not found"

  • Verify group ID is correct
  • Check group exists
  • Use GET /api/groups to list groups
  • Create group if needed

Error: "Cognito error"

  • Check Cognito configuration
  • Verify user pool ID
  • Check IAM permissions
  • Review Cognito error logs

User Can't Log In

Check:

  1. User exists in system
  2. Account is enabled (not disabled)
  3. Password is correct
  4. Cognito user exists
  5. Email is verified

Solutions:

  • Reset password
  • Enable account if disabled
  • Verify email in Cognito
  • Check Cognito status
  • Review auth logs

Group Membership Issues

User Not Seeing Group:

  • Verify user added to group
  • Check group membership API
  • Refresh browser/re-login
  • Check group exists

User Can't Create Workspace:

  • Verify group membership
  • Check group has resources
  • Verify user role
  • Check for errors in logs

Next Steps

← Admin Overview | Privilege Guidelines →

Clone this wiki locally