# 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](/product/administration/agent-permissions.md) - 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](/product/security/best-practices.md) - Secure your org --- # 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-permissions.md?ask= ``` 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.