# User Management

Add users, assign roles, and control access.

## Overview

**Location**: Admin → Users

**Actions available**:

* Invite users (email invitation)
* Assign roles (ReadOnly, Train, Configure, Admin)
* Add to groups (bulk permission assignment)
* Monitor activity (queries, logins, last active)
* Deactivate/delete users

## Add Users

### Invite Individual User

**Location**: Admin → Users → Invite User button

1. Click **Invite User**
2. Fill form:
   * **Email**: <user@company.com> (required, validated)
   * **Name**: Full name (optional)
   * **Role**: Dropdown (readonly, train, configure, admin)
   * **Groups**: Multi-select (optional)
3. Click **Send Invitation**

**Expected result**:

* Invitation sent to email
* User appears in list with status "Pending" (gray dot)
* Invitation expires after 7 days
* Resend link available

**Email contains**:

* Setup link (format: app.twig.so/invite/token\_abc123)
* Expires timestamp
* Inviter name

### Bulk Import (CSV)

**Location**: Admin → Users → Import button

**CSV format**:

```csv
email,name,role,groups
john@company.com,John Doe,train,"Support Team"
jane@company.com,Jane Smith,readonly,"Sales Team;Engineering"
```

**Fields**:

* `email`: Required, must be valid format
* `name`: Optional
* `role`: One of: `readonly`, `train`, `configure`, `admin`
* `groups`: Optional, pipe-separated or semicolon-separated

**Steps**:

1. Download template CSV
2. Fill rows (max 1,000 per import)
3. Upload CSV
4. Review preview (shows: add, skip, error counts)
5. Confirm import

**Expected result**: Users added with status "Pending", invitations sent

### SSO Auto-Provisioning (Enterprise)

**Location**: Admin → SSO → Auto-Provisioning tab

**Enable Just-In-Time (JIT) provisioning**:

1. Toggle **Enable JIT** → On
2. Configure:
   * **Default role**: Dropdown (default: readonly)
   * **Email attribute**: SAML/OIDC attribute name (e.g., `email`, `mail`)
   * **Name attribute**: Optional (e.g., `displayName`)
   * **Group attribute**: Optional (e.g., `memberOf`)
3. Click **Save**

**Behavior**: User created automatically on first SSO login, no invitation needed

**Example SAML attribute mapping**:

```xml
<saml:Attribute Name="email">user@company.com</saml:Attribute>
<saml:Attribute Name="displayName">John Doe</saml:Attribute>
<saml:Attribute Name="memberOf">Support Team</saml:Attribute>
```

## User Roles

See [User Permissions & Roles](/product/administration/user-permissions.md) for complete details.

**Quick Reference:**

| Role            | Can Create Agents | Can Edit All Agents | Can Manage Users | Can View All Analytics |
| --------------- | ----------------- | ------------------- | ---------------- | ---------------------- |
| **Super Admin** | ✅                 | ✅                   | ✅                | ✅                      |
| **Admin**       | ✅                 | ✅                   | ✅                | ✅                      |
| **Manager**     | ✅                 | Own only            | Group only       | Group only             |
| **User**        | ❌                 | ❌                   | ❌                | Self only              |

## Managing Users

### Viewing Users

**User List shows:**

* Name and email
* Role
* Groups
* Last login
* Status (Active/Inactive)
* Actions

**Filters:**

* By role
* By group
* By status
* By last login date

### Editing Users

1. Click on user
2. Modify:
   * Name
   * Role
   * Groups
   * Status
3. Save changes
4. User notified (optional)

### Changing Roles

1. Select user
2. Click **Change Role**
3. Select new role
4. Confirm impact warning
5. Save

**Effect:** Immediate permission changes

### Deactivating Users

**Temporary deactivation:**

1. Select user
2. Click **Deactivate**
3. Confirm

**Effects:**

* Cannot log in
* API keys disabled
* Removed from groups temporarily
* Data preserved

**Reactivation:**

1. Select deactivated user
2. Click **Activate**
3. Restore group memberships

### Deleting Users

⚠️ **Permanent action**

1. Select user
2. Click **Delete**
3. Choose deletion mode:
   * **Soft Delete**: Hide user, keep data
   * **Hard Delete**: Remove completely
4. Confirm with admin password
5. User removed

## Group Assignment

### Adding to Groups

**Individual:**

1. Open user profile
2. Go to **Groups** tab
3. Click **Add to Group**
4. Select group(s)
5. Save

**Bulk:**

1. Select multiple users
2. Bulk Actions → **Add to Group**
3. Select group
4. Confirm

### Removing from Groups

1. Open user profile
2. Groups tab
3. Click **X** next to group name
4. Confirm removal

## User Activity Monitoring

### Activity Dashboard

```
User: john@company.com
├─ Last Login: 2 hours ago
├─ Queries (24h): 45
├─ Most Used Agent: Support Agent
├─ Avg Response Time: 1.8s
├─ Failed Auth: 0
└─ Status: Active ✅
```

### Activity Logs

Track user actions:

* Logins and logouts
* Agents used
* Queries asked
* Resources accessed
* Configuration changes
* Failed attempts

### Anomaly Detection

Auto-alert on:

* Login from new location
* Unusual query volume
* Failed auth attempts (5+)
* Access to sensitive resources
* Off-hours activity (configurable)

## Best Practices

### 1. Onboarding

✅ Standard onboarding checklist ✅ Role assignment based on job function ✅ Group assignment from day 1 ✅ Security training required ❌ Don't grant broad access initially

### 2. Offboarding

✅ Deactivate immediately on departure ✅ Remove from all groups ✅ Revoke API keys ✅ Transfer ownership of resources ✅ Export user data if needed ❌ Don't delay deactivation

### 3. Regular Reviews

✅ Quarterly access review ✅ Remove inactive users (90+ days) ✅ Verify role appropriateness ✅ Update group memberships ❌ Don't let permissions accumulate

### 4. Principle of Least Privilege

✅ Start with User role ✅ Escalate only when needed ✅ Time-limit elevated access ✅ Document justification ❌ Don't make everyone Manager/Admin

## Troubleshooting

### User Can't Login

**Symptom**: "Invalid email or password" or "Account not found"

**Diagnostic steps**:

1. Admin → Users → search by email → verify status "Active" (not "Pending" or "Inactive")
2. Check invitation status: If "Pending", user must click invite link first
3. If SSO: Admin → SSO → verify enabled and user's email domain in allowed list
4. Check account lockout: Admin → Users → \[User] → Security tab → Failed logins count

**Fix**:

* If "Pending": Resend invitation (Admin → Users → \[User] → Resend Invite)
* If "Inactive": Click **Activate** button
* If locked out (5+ failed attempts): Click **Unlock Account**
* If SSO misconfigured: Fix SSO settings or have user use password login

***

### User Missing Permissions

**Symptom**: User reports "You don't have permission to access this" error

**Diagnostic steps**:

1. Admin → Users → \[User] → verify role (should be train/configure/admin for most features)
2. Check groups: If permission is group-based, verify user in correct group
3. Have user log out and log back in (permissions cached for 5 minutes)

**Fix**: Change role (Admin → Users → \[User] → Edit → Role dropdown) or add to group

***

### Bulk Import Failed

**Symptom**: Import shows errors for some rows

**Common errors**:

* "Invalid email format" → Fix email syntax (must have @)
* "Duplicate email" → Email already exists, skip or update role
* "Invalid role" → Must be exactly: `readonly`, `train`, `configure`, `admin` (lowercase)
* "Group not found" → Create group first, or remove from CSV

**Fix**: Download error CSV (shows which rows failed), fix errors, re-import

## Next Steps

[Group Management](/product/administration/group-management.md) - Organize users into teams

[User Permissions](/product/administration/user-permissions.md) - Understand role capabilities


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.twig.so/product/administration/user-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.