User Management

Users are the individuals or groups who make requests to your Admin Bud-E instance. Each user has:

• A unique username (identifier)
• An API key (for authentication)
• A credit balance (for usage tracking)
• A project assignment (for shared budgets)
• Optional: allowance (periodic credits from project)
• Optional: common pool access (shared credits)

User Overview

In the Admin UI, navigate to Users to see:

• List of all users
• Current credit balances
• Project assignments
• API key status (active/inactive)
• Filters and search

Creating Users

Method 1: Manual Creation

1. Navigate to Users
2. Click Create User
3. Fill in:
   • Username: Unique identifier (e.g., teacher-smith, class-5a, student-12345)
   • Project: Select from dropdown (or leave unassigned)
   • Initial Credits: Starting balance (e.g., 1000)
4. Click Save

The system automatically generates a secure API key.

Method 2: Bulk Import (CSV)

For schools and organizations with many users:

1. Prepare a CSV file with columns:

   username,project,initial_credits
   teacher-smith,teachers,5000
   teacher-jones,teachers,5000
   class-5a,students,1000
   class-5b,students,1000

2. Navigate to Users → Import

3. Upload your CSV file

4. Review the preview

5. Click Confirm Import

TIP

CSV import is the fastest way to onboard 50+ users. API keys are generated automatically.

Understanding Credit Balances

Each user has multiple credit "pools" that are consumed in order:

1. Allowance (if enabled)

Periodic credits granted by the project (daily, weekly, or monthly). This refreshes automatically.

Example:

• Project "Teachers" grants 100 credits/day
• User has 75 allowance credits remaining

2. Common Pool (if enabled)

Shared credits available to all project members. Used after allowance is depleted.

Example:

• Project has 5,000 common pool credits
• User can draw from this when allowance runs out

3. Personal Credits

Credits assigned directly to the user. These don't refresh automatically.

Example:

• User has 200 personal credits
• Used after allowance and common pool

Consumption Order

Request → Check Allowance → Check Common Pool → Check Personal Credits → Reject

If any pool has sufficient credits, the request succeeds.

INFO

"Effective Credits" = Allowance + (Common Pool share) + Personal Credits

API Keys

Viewing API Keys

For security, API keys are hidden by default in the user list.

To reveal a user's key:

1. Click View Key next to the user
2. Copy the key
3. Share it securely with the user (encrypted email, password manager, etc.)

WARNING

Never share API keys in plain text emails, chat messages, or screenshots that might be shared.

Rotating API Keys

If a key is compromised or needs to be changed:

1. Navigate to Users
2. Click Rotate Key for the user
3. Confirm the action
4. Old key is immediately invalidated
5. Copy the new key and share it with the user

DANGER

Key rotation breaks existing integrations immediately. Update all clients using the old key.

Deactivating Users

To temporarily disable a user without deleting them:

1. Navigate to Users
2. Click Deactivate for the user
3. Confirm

Effect:

• API key no longer works
• User cannot make requests
• Credit balance is preserved
• Can be reactivated later

Reactivating Users

To restore access:

1. Navigate to Users
2. Click Activate for the user
3. Confirm

The user's existing API key becomes valid again.

Editing Users

To modify user details:

1. Navigate to Users
2. Click Edit for the user
3. Update fields:
   • Username (if no usage history)
   • Project assignment
   • Personal credits (add/subtract)
4. Click Save

INFO

You cannot change the username if the user has usage history. Create a new user instead.

Deleting Users

To permanently remove a user:

1. Navigate to Users
2. Click Delete for the user
3. Confirm deletion

DANGER

This action:

• Deletes the user and their API key
• Preserves usage history (for audit trails)
• Cannot be undone

Before deleting, consider deactivating instead.

Managing Credits

Adding Credits

To grant additional personal credits:

1. Navigate to Users
2. Click Edit for the user
3. Add to Personal Credits field
4. Click Save

Example:

• Current balance: 500
• Add 1,000
• New balance: 1,500

Deducting Credits

To remove credits (e.g., correction, abuse):

1. Navigate to Users
2. Click Edit
3. Subtract from Personal Credits
4. Add a note in a comment field (if available)
5. Click Save

TIP

Log manual credit adjustments externally (spreadsheet, admin log) for auditing.

Credit Transfers

To move credits between users:

1. Deduct from User A
2. Add to User B
3. Note the transfer in both records

INFO

Future versions may include a dedicated "Transfer Credits" feature.

Filters and Search

The user list supports:

Search by Username

Type in the search box to filter by username.

Filter by Project

Select a project from the dropdown to show only users in that project.

Filter by Status

• Active: Users who can make requests
• Inactive: Deactivated users

Sort Options

• Username (A-Z)
• Credits (high to low)
• Recent Activity (most recent first)

User Usage Reports

To see detailed usage for a specific user:

1. Navigate to Usage
2. Filter by User → select the username
3. Set date range (or leave empty for current month)
4. Click Preview or Export

See Usage Reports for details.

Project Assignment

Why Assign Projects?

Projects enable:

• Shared budgets (common pool)
• Periodic allowances (daily/weekly/monthly credits)
• Grouped reporting (usage per project)
• Administrative organization (teachers, students, staff)

Assigning Users to Projects

During creation:

1. Select project from dropdown when creating user

After creation:

1. Navigate to Users
2. Click Edit for the user
3. Change Project dropdown
4. Click Save

TIP

Reassignment takes effect immediately and affects allowance eligibility.

Unassigned Users

Users without a project:

• Have no allowance
• Cannot access common pool
• Can only use personal credits

Best Practices

Naming Conventions

Use clear, consistent usernames:

Good:

• teacher-smith
• class-5a
• dept-math
• student-00123

Avoid:

• Personal names (GDPR: john.doe → use student-00123)
• Email addresses (not needed, privacy risk)
• Special characters (stick to letters, numbers, hyphens)

Initial Credits

For testing:

• 10-100 credits (enough for a few dozen requests)

For teachers/staff:

• 1,000-10,000 credits (depending on expected usage)

For students:

• 100-1,000 credits (or rely on allowance instead)

TIP

Start conservative. It's easier to add credits than to take them back.

Security

1. Distribute keys securely

   • Use encrypted email or a password manager
   • Never post in public forums or group chats

2. Rotate keys regularly

   • Set a schedule (every 90 days)
   • Rotate immediately if compromised

3. Monitor unusual usage

   • Check usage reports for spikes
   • Investigate users with zero balance (possible abuse)

4. Deactivate inactive users

   • If a user leaves, deactivate their key
   • Archive data but remove access

CSV Export

To export the user list:

1. Navigate to Users
2. Apply any filters (optional)
3. Click Export CSV
4. Save the file

CSV includes:

• Username
• Project
• Personal credits
• Effective credits
• Status (active/inactive)
• Last activity date (if tracked)

Use this for:

• Backup
• External reporting
• Integration with school systems

Troubleshooting

User Can't Authenticate

Problem: "Invalid API key" error.

Possible causes:

1. User is deactivated → reactivate
2. API key was rotated → provide new key
3. Typo in key → verify exact string
4. Key expired (if expiration enabled) → generate new key

User Has Zero Credits But Allowance Enabled

Problem: User shows 0 effective credits despite project allowance.

Possible causes:

1. Allowance period hasn't refreshed yet → wait or manually settle
2. Common pool is depleted → add credits to project
3. User is not in a project with allowance → check project assignment

Cannot Delete User

Problem: Delete button is disabled or fails.

Possible cause: User has active sessions or pending requests.

Solution: Deactivate first, wait 5 minutes, then delete.

Next Steps

• Set up projects for shared budgets
• Configure allowances and common pools
• Review user usage reports
• Understand privacy and data handling