# User Permissions & Roles Comprehensive guide to user permissions, roles, and access control in Twig AI. ## Overview Role-Based Access Control (RBAC) determines user permissions. **4 roles** (from least to most permissions): 1. **User** (readonly): Query agents only 2. **Manager**: Create agents, manage team resources 3. **Admin**: Full agent/data management, user management 4. **Super Admin**: All permissions + billing + org deletion **Assigned**: Admin → Users → \[User] → Edit → Role dropdown ## User Roles ### Role Hierarchy ``` Super Admin (Highest) ↓ Admin ↓ Manager ↓ User (Base) ``` ### Role Definitions #### Super Admin **Description:** Complete platform control, typically for organization owners and IT administrators. **Permissions:** | Category | Permissions | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Organization** |

• Full administrative access
• Manage billing and subscriptions
• Delete organization
• Configure SSO
• Manage integrations

| | **Users** |

• Create, edit, delete all users
• Assign any role including Super Admin
• Manage all groups
• View all user activity

| | **Agents** |

• Create, edit, delete all agents
• Access all agents regardless of restrictions
• Manage agent permissions
• View all agent analytics

| | **Data Sources** |

• Create, edit, delete all data sources
• Trigger processing for any source
• View connection credentials
• Configure refresh schedules

| | **Analytics** |

• Access all analytics dashboards
• Export all data
• View organization-wide metrics
• Access super admin dashboard

| | **Settings** |

• Modify all system settings
• Configure security policies
• Manage API keys
• Access audit logs

| **Use Cases:** * Organization founders/owners * IT administrators * Platform administrators **Assignment:** Limited to 2-3 users per organization (recommended) #### Admin **Description:** Day-to-day administrative control without billing or critical system changes. **Permissions:** | Category | Permissions | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Organization** |

• View organization settings
• Manage integrations
• ❌ Cannot delete organization
• ❌ Cannot change billing

| | **Users** |

• Create, edit, delete users (except Super Admins)
• Assign roles (up to Manager)
• Manage groups
• View user activity

| | **Agents** |

• Create, edit, delete all agents
• Access all agents
• Manage agent permissions
• View all agent analytics

| | **Data Sources** |

• Create, edit, delete all data sources
• Trigger processing
• ❌ Cannot view credentials (encrypted)
• Configure refresh schedules

| | **Analytics** |

• Access admin dashboards
• Export organization data
• View all metrics
• Generate reports

| | **Settings** |

• Modify most settings
• Manage API keys for organization
• View audit logs
• ❌ Cannot modify security policies

| **Use Cases:** * Team leads * Department heads * Operations managers **Assignment:** 5-10 users typically #### Manager **Description:** Team-level management with permissions for their department or group. **Permissions:** | Category | Permissions | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Organization** |

• View organization settings
• ❌ Cannot modify
• ❌ Cannot manage integrations

| | **Users** |

• View users in their groups
• Add/remove users from their groups
• ❌ Cannot create/delete users
• ❌ Cannot assign roles

| | **Agents** |

• Create agents
• Edit agents they created or are assigned
• Delete agents they created
• Assign agents to their groups
• View analytics for their agents

| | **Data Sources** |

• Create data sources
• Edit data sources they created
• Trigger processing for their sources
• ❌ Cannot delete data sources
• View their data source analytics

| | **Analytics** |

• Access management dashboard
• View metrics for their groups/agents
• Export their team's data
• ❌ Cannot view org-wide sensitive metrics

| | **Settings** |

• Manage their own API keys
• View limited audit logs (their actions)
• ❌ Cannot modify system settings

| **Use Cases:** * Team managers * Project leads * Department supervisors **Assignment:** Team/project leaders #### User **Description:** Standard user access for day-to-day use of AI agents. **Permissions:** | Category | Permissions | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Organization** |

• View basic organization info
• ❌ Cannot modify anything

| | **Users** |

• View their own profile
• Update their own settings
• ❌ Cannot see other users
• ❌ Cannot manage groups

| | **Agents** |

• Use agents they have access to
• View responses and citations
• ❌ Cannot create agents
• ❌ Cannot edit agents
• ❌ Cannot change agent settings

| | **Data Sources** |

• ❌ Cannot access data sources
• ❌ Cannot view data source list
• ❌ Cannot create/edit/delete

| | **Analytics** |

• View their own usage statistics
• See their interaction history
• ❌ Cannot view team metrics
• ❌ Cannot export data

| | **Settings** |

• Update profile (name, photo)
• Manage notification preferences
• Generate personal API keys (if enabled)
• ❌ Cannot modify system settings

| **Use Cases:** * End users * Employees using AI assistance * External users (with restrictions) **Assignment:** All standard users ## Permission Matrix ### Complete Permission Reference | Permission | Super Admin | Admin | Manager | User | | ----------------------------- | ----------- | ----------------- | ------------- | ---------- | | **Organization Management** | | | | | | View organization | ✅ | ✅ | ✅ | ✅ | | Edit organization settings | ✅ | ✅ | ❌ | ❌ | | Delete organization | ✅ | ❌ | ❌ | ❌ | | Manage billing | ✅ | ❌ | ❌ | ❌ | | Configure SSO | ✅ | ✅ | ❌ | ❌ | | **User Management** | | | | | | View all users | ✅ | ✅ | Group only | Self only | | Create users | ✅ | ✅ | ❌ | ❌ | | Edit users | ✅ | ✅ | ❌ | Self only | | Delete users | ✅ | ✅ | ❌ | ❌ | | Assign roles | ✅ | ✅ (up to Manager) | ❌ | ❌ | | **Group Management** | | | | | | View groups | ✅ | ✅ | Assigned only | ❌ | | Create groups | ✅ | ✅ | ❌ | ❌ | | Edit groups | ✅ | ✅ | Own groups | ❌ | | Delete groups | ✅ | ✅ | ❌ | ❌ | | Add/remove members | ✅ | ✅ | Own groups | ❌ | | **Agent Management** | | | | | | View agents | ✅ All | ✅ All | Assigned | Assigned | | Create agents | ✅ | ✅ | ✅ | ❌ | | Edit agents | ✅ All | ✅ All | Own/Assigned | ❌ | | Delete agents | ✅ | ✅ | Own only | ❌ | | Manage agent permissions | ✅ | ✅ | Own agents | ❌ | | Use agents in Playground | ✅ | ✅ | ✅ | ✅ | | **Data Source Management** | | | | | | View data sources | ✅ | ✅ | Own only | ❌ | | Create data sources | ✅ | ✅ | ✅ | ❌ | | Edit data sources | ✅ | ✅ | Own only | ❌ | | Delete data sources | ✅ | ✅ | ❌ | ❌ | | Trigger processing | ✅ | ✅ | ✅ | ❌ | | View connection credentials | ✅ | ❌ | ❌ | ❌ | | **Analytics & Reporting** | | | | | | View super admin dashboard | ✅ | ❌ | ❌ | ❌ | | View admin dashboard | ✅ | ✅ | ❌ | ❌ | | View management dashboard | ✅ | ✅ | ✅ | ❌ | | View user dashboard | ✅ | ✅ | ✅ | ✅ | | Export data | ✅ | ✅ | Own data | Own data | | View interaction history | ✅ All | ✅ All | Group only | Self only | | **Inbox & Training** | | | | | | View all interactions | ✅ | ✅ | Group only | Self only | | Edit responses | ✅ | ✅ | ✅ | ❌ | | Mark as accurate/inaccurate | ✅ | ✅ | ✅ | ❌ | | Create KB articles from inbox | ✅ | ✅ | ✅ | ❌ | | **Knowledge Base** | | | | | | View KB articles | ✅ | ✅ | ✅ | ✅ | | Create KB articles | ✅ | ✅ | ✅ | ❌ | | Edit KB articles | ✅ | ✅ | Own only | ❌ | | Delete KB articles | ✅ | ✅ | ❌ | ❌ | | Manage KB tags | ✅ | ✅ | ❌ | ❌ | | **API & Integration** | | | | | | View org API keys | ✅ | ✅ | ❌ | ❌ | | Create org API keys | ✅ | ✅ | ❌ | ❌ | | Create personal API keys | ✅ | ✅ | ✅ | If enabled | | Manage webhooks | ✅ | ✅ | ❌ | ❌ | | Configure integrations | ✅ | ✅ | ❌ | ❌ | | **Security & Audit** | | | | | | View audit logs | ✅ All | ✅ All | Self only | ❌ | | Configure security policies | ✅ | ❌ | ❌ | ❌ | | Manage SSO | ✅ | ✅ | ❌ | ❌ | | View sensitive data | ✅ | ❌ | ❌ | ❌ | ## Managing User Permissions ### Creating Users with Roles **Method 1: Individual User Creation** 1. Navigate to **Administration** → **Users** 2. Click **Create New User** 3. Fill in user details: * **Email**: (required) * **Name**: Full name * **Role**: Select from dropdown * **Groups**: Assign to groups (optional) * **Status**: Active/Inactive 4. Click **Send Invitation** 5. User receives email with setup link **Method 2: Bulk User Import** 1. Administration → Users → **Import Users** 2. Download CSV template 3. Fill in user details: ```csv Email,Name,Role,Groups,Status john@company.com,John Doe,MANAGER,"Support Team,Tier 2",ACTIVE jane@company.com,Jane Smith,USER,"Support Team",ACTIVE ``` 4. Upload CSV file 5. Review and confirm import 6. Users receive invitations automatically **Method 3: SSO Auto-Provisioning** 1. Administration → SSO → **Auto-Provisioning** 2. Enable **Just-In-Time (JIT) Provisioning** 3. Configure default role: User (typically) 4. Map SSO attributes to user fields: ``` SSO Attribute → Twig Field email → email displayName → name department → default_group jobTitle → custom_field ``` 5. Users created automatically on first login ### Changing User Roles **Single User:** 1. Administration → Users → Select user 2. Click **Edit** 3. Change **Role** dropdown 4. Confirm: "Are you sure? This will change permissions immediately." 5. Click **Save** **Bulk Role Change:** 1. Administration → Users 2. Select multiple users (checkbox) 3. Bulk Actions → **Change Role** 4. Select new role 5. Confirm changes 6. Users notified of permission change (optional) ### Deactivating Users **Temporary Deactivation:** 1. Administration → Users → Select user 2. Click **Deactivate** 3. User status: Inactive 4. Effects: * Cannot log in * API keys disabled * Removed from groups (temporarily) * Data and history preserved **Permanent Deletion:** 1. Administration → Users → Select user 2. Click **Delete** 3. Select deletion mode: * **Soft Delete**: User hidden, data preserved * **Hard Delete**: User and all data removed (irreversible) 4. Confirm deletion 5. Effects: * User completely removed * Group memberships removed * API keys revoked * Owned agents reassigned or deleted ## Custom Permissions ### Fine-Grained Control (Enterprise) Enterprise customers can create custom permission sets: **Example: "Data Analyst" Custom Role** ```json { "roleName": "Data Analyst", "baseRole": "USER", "additionalPermissions": [ "VIEW_ALL_ANALYTICS", "EXPORT_DATA", "VIEW_INTERACTION_HISTORY", "CREATE_REPORTS" ], "restrictions": [ "CANNOT_EDIT_AGENTS", "CANNOT_CREATE_AGENTS", "CANNOT_MODIFY_DATA_SOURCES" ] } ``` **Setup:** 1. Contact support or use Enterprise API 2. Define custom role with specific permissions 3. Assign to users 4. Custom role appears in role dropdown ### Resource-Level Permissions Control access at the individual resource level: **Example: Agent-Specific Permissions** ``` User: john@company.com ├─ Agent 1: View & Use ├─ Agent 2: Edit ├─ Agent 3: No Access └─ Agent 4: View Only (no use) ``` **Configuration:** 1. Open Agent → Settings → Permissions 2. Click **Add User Permission** 3. Search for user 4. Select permission level: * **No Access**: Cannot see agent * **View Only**: Can see but not use * **View & Use**: Can query agent * **Edit**: Can modify settings * **Manage**: Full control including deletion 5. Save ## Permission Scenarios ### Scenario 1: Customer Support Organization **Roles & Groups:** ``` Super Admin (1) └─ CEO Admin (2) ├─ Head of Support └─ IT Manager Manager (5) ├─ Support Team Lead (Group: Support Team) ├─ Sales Team Lead (Group: Sales Team) └─ Engineering Lead (Group: Engineering) User (100+) ├─ Support Agents → Group: Support Team ├─ Sales Reps → Group: Sales Team └─ Engineers → Group: Engineering ``` **Agent Access:** * Support Agent → Support Team group only * Sales Agent → Sales Team group only * Engineering Agent → Engineering group + private data ### Scenario 2: Multi-Tenant Consulting Firm **Structure:** ``` Super Admin └─ Firm Owner Admin (per client) ├─ Client A Admin → Group: Client A ├─ Client B Admin → Group: Client B └─ Client C Admin → Group: Client C Manager (per client) ├─ Client A Consultants → Group: Client A └─ Client B Consultants → Group: Client B User └─ Consultants assigned to client groups ``` **Agent Isolation:** * Each client has dedicated agents * Agents restricted to client-specific groups * Data sources scoped per client * Complete data isolation ### Scenario 3: Enterprise with Contractors **Setup:** ``` Internal Users ├─ Super Admin (2) ├─ Admin (5) ├─ Manager (20) └─ User (500) External Users └─ Contractor (50) ├─ Group: External Contractors ├─ Role: User (limited) └─ Restrictions: • No data export • No analytics access • Time-limited access • Specific agents only ``` **Contractor Permissions:** * Cannot view organization settings * Cannot see other users * Cannot create/edit agents * Can only use assigned agents * No API access * Session timeout: 30 minutes (vs 8 hours for internal) ## Security Best Practices ### 1. Role Assignment ✅ **Do:** * Assign minimum necessary role * Regular role reviews (quarterly) * Document why Super Admins are needed * Limit Super Admins to 2-3 maximum * Use Manager role for team leads * Default new users to User role ❌ **Don't:** * Give everyone Admin role "just in case" * Make all managers Super Admins * Skip role justification * Forget to review after org changes ### 2. Principle of Least Privilege Implement progressively: **Week 1:** Assign basic roles **Month 1:** Add group-based restrictions **Month 3:** Implement resource-level permissions **Month 6:** Fine-tune based on usage patterns ### 3. Access Reviews **Monthly:** * Review new user assignments * Check for role escalations * Verify group memberships **Quarterly:** * Full permission audit * Recertify privileged access (Admin+) * Remove unused accounts * Update group structures **Annually:** * Review role definitions * Update permission policies * Train admins on permission management ### 4. Segregation of Duties For sensitive operations: | Action | Required Role | Approval Required | | ------------------------- | ------------- | ----------------- | | Create agent | Manager+ | No | | Add sensitive data source | Admin+ | Manager approval | | Export all org data | Super Admin | CEO approval | | Delete organization | Super Admin | Board approval | | Change security policy | Super Admin | CISO approval | ## Monitoring & Auditing ### Permission Change Logs All permission changes are logged: **View Logs:** ``` Administration → Audit Logs → Filter: Permission Changes ``` **Logged Events:** * Role changes * Group membership changes * Permission grants/revokes * User activations/deactivations * Role definition changes **Example Log:** ```json { "timestamp": "2024-01-15T14:30:00Z", "event": "ROLE_CHANGED", "actor": "admin@company.com", "subject": "user@company.com", "changes": { "role": { "from": "USER", "to": "MANAGER" } }, "reason": "Promoted to team lead", "ipAddress": "192.168.1.1" } ``` ### Access Reports **Available Reports:** 1. **User Permissions Report** * All users with their roles and groups * Export to CSV 2. **Privileged Access Report** * All Admins and Super Admins * Last login, last activity * Requires quarterly recertification 3. **Inactive Users Report** * Users who haven't logged in (configurable period) * Candidates for deactivation 4. **Permission Changes Report** * All permission changes in period * Grouped by type, user, or actor ## API Access Control ### API Key Permissions API keys inherit user permissions: | User Role | API Key Capabilities | | --------------- | -------------------------------------- | | **Super Admin** | Full API access, all operations | | **Admin** | Most operations, excluding billing | | **Manager** | CRUD for own resources, read for group | | **User** | Chat/completion, read own data | ### Scoped API Keys Create API keys with limited scope: ```bash curl -X POST https://api.twig.so/api/api-keys \ -H "Authorization: Bearer YOUR_KEY" \ -d '{ "name": "Production Chat API", "scope": ["CHAT", "VIEW_AGENTS"], "agentIds": ["agent-1", "agent-2"], "rateLimit": 1000, "expiresAt": "2024-12-31" }' ``` **Scope Options:** * `CHAT`: Chat/completion requests only * `VIEW_AGENTS`: List and read agents * `MANAGE_AGENTS`: Create/edit/delete agents * `VIEW_DATA`: Read data sources and analytics * `MANAGE_DATA`: Modify data sources * `ADMIN`: Full administrative access ## Troubleshooting ### User Can't Perform Action **Diagnosis:** 1. Check user's role: Administration → Users → \[User] 2. Check group memberships 3. Check resource-specific permissions 4. Review audit logs for any restrictions **Common Issues:** **Insufficient Role:** ``` Error: "You don't have permission to create agents" Solution: User role must be Manager or higher ``` **Not in Group:** ``` Error: "Agent not found" Solution: Agent is group-restricted; add user to group ``` **Resource-Specific Restriction:** ``` Error: "You can only edit agents you created" Solution: User is Manager; only Admins can edit all agents ``` ### Permission Changes Not Taking Effect **Solutions:** 1. Have user log out and back in 2. Clear browser cache 3. Check session timeout settings 4. If SSO, verify attribute sync ## Next Steps * [Agent Permissions](https://help.twig.so/product/administration/agent-permissions) - Control agent access * [Group Management](https://github.com/thrivapp/twig-help-docs/blob/staging/administration/group-management.md) - Organize users * [SSO Integration](https://github.com/thrivapp/twig-help-docs/blob/staging/security/sso-integration.md) - Enterprise authentication * [Audit Logs](https://github.com/thrivapp/twig-help-docs/blob/staging/administration/audit-logs.md) - Track all activities * [Security Best Practices](https://help.twig.so/product/security/best-practices) - Secure your org