User Permissions & Roles

Comprehensive guide to user permissions, roles, and access control in Twig AI.

Overview

Twig AI uses Role-Based Access Control (RBAC) to manage what users can see and do within the platform. Permissions are assigned through roles, groups, and direct assignments.

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: [email protected] (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:

   Email,Name,Role,Groups,Status
   [email protected],John Doe,MANAGER,"Support Team,Tier 2",ACTIVE
   [email protected],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

{
  "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: [email protected]
├─ 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:

{
  "timestamp": "2024-01-15T14:30:00Z",
  "event": "ROLE_CHANGED",
  "actor": "[email protected]",
  "subject": "[email protected]",
  "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:

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 - Control agent access

• Group Management - Organize users

• SSO Integration - Enterprise authentication

• Audit Logs - Track all activities

• Security Best Practices - Secure your org