Agent Permissions & Access Control

Control who can view, use, and manage AI agents in your organization using groups and role-based access control.

Overview

Agent permissions in Twig AI enable you to:

• Restrict agent access to specific users or groups

• Control agent visibility across the organization

• Manage who can edit agent configurations

• Enforce data access policies through agent restrictions

Permission Model

Access Levels

Agents support three access control models:

Access Type	Description	Who Can Use
Public (Organization)	Available to all users in the organization	Everyone
Group-Restricted	Only specific groups can access	Selected groups only
Private	Only creator and admins can access	Creator + Admins

Role-Based Control

Different roles have different permissions for agents:

Role	View Agents	Use Agents	Edit Agents	Delete Agents	Manage Permissions
Super Admin	All	All	All	All	✅
Admin	All	All	All	All	✅
Manager	Assigned	Assigned	Assigned	❌	Limited
User	Assigned	Assigned	❌	❌	❌

Setting Up Agent Permissions

Step 1: Create Groups

Groups are collections of users that can be assigned permissions together.

To create a group:

1. Navigate to Administration → Groups

2. Click Create New Group

3. Configure the group:

   • Name: e.g., "Customer Support Team"

   • Description: "Customer-facing support agents"

   • Members: Add users to the group

4. Click Save

Best Practices for Groups:

• Organize by department (Sales, Support, Engineering)

• Create role-based groups (Managers, Analysts)

• Use project-based groups for temporary access

• Name groups clearly and descriptively

Step 2: Assign Agents to Groups

Method 1: From Agent Settings

1. Open the agent you want to restrict

2. Go to Settings → Permissions

3. Select Access Type:

   • Organization-Wide: All users can access

   • Group-Restricted: Only selected groups

   • Private: Only you and admins

4. If Group-Restricted, select groups:

   • Click Add Group

   • Select one or more groups

   • Groups can have different permission levels

5. Click Save

Method 2: From Group Settings

1. Navigate to Administration → Groups

2. Open the group

3. Go to Agents tab

4. Click Add Agent

5. Select agents to add

6. Choose permission level:

   • View & Use: Can query the agent

   • Edit: Can modify agent settings

7. Click Save

Step 3: Add Users to Groups

To add users to a group:

1. Navigate to Administration → Groups

2. Open the group

3. Go to Members tab

4. Click Add Members

5. Select users from the list or search by name/email

6. Assign role within group (optional):

   • Member: Standard access

   • Manager: Can add/remove members

7. Click Add

Bulk User Assignment:

• Import users via CSV: Name, Email, Group

• Use API for programmatic assignment

• Sync with SSO groups (Enterprise)

Permission Scenarios

Scenario 1: Department-Specific Agents

Use Case: Create agents that only specific departments can use.

Setup:

1. Create groups:

   • "Sales Team"

   • "Support Team"

   • "Engineering Team"

2. Create agents:

   • "Sales Agent" → Assign to "Sales Team" group

   • "Support Agent" → Assign to "Support Team" group

   • "Engineering Agent" → Assign to "Engineering Team"

3. Result:

   • Sales team only sees and can use Sales Agent

   • Support team only has access to Support Agent

   • Engineering team only has access to Engineering Agent

Scenario 2: Multi-Level Access

Use Case: Some users need access to multiple agents.

Setup:

1. Create groups:

   • "Tier 1 Support" → Access to Basic Support Agent

   • "Tier 2 Support" → Access to Basic + Advanced Support Agent

   • "Support Managers" → Access to all Support Agents + Edit permissions

2. Assign users:

   • Junior agents → Tier 1 Support group

   • Senior agents → Tier 2 Support group

   • Managers → Support Managers group

3. Result:

   • Graduated access based on experience level

   • Managers can modify agent configurations

   • Users only see relevant agents

Scenario 3: Project-Based Access

Use Case: Temporary access for project teams.

Setup:

1. Create group: "Product Launch Q1 2024"

2. Add cross-functional team members

3. Assign relevant agents:

   • Product Documentation Agent

   • Marketing Content Agent

   • Sales Enablement Agent

4. Set expiration date (manual or via API)

5. After project completion:

   • Remove users from group

   • Archive or delete group

   • Agent access automatically revoked

Scenario 4: Customer Success with Data Restrictions

Use Case: External consultants need limited access.

Setup:

1. Create group: "External Consultants"

2. Create agent: "Client-Facing Assistant"

   • Data Sources: Only public documentation

   • Private Data: Disabled

   • Features: No editing, no analytics

3. Assign group to agent with "View & Use" only

4. Result:

   • Consultants can use agent for customer queries

   • Cannot access internal data

   • Cannot see organization analytics

   • Cannot modify agent settings

Advanced Permission Controls

Data Source-Level Permissions

Combine agent permissions with data source restrictions:

Example:

Agent: "Product Documentation Assistant"
├─ Assigned to: "Support Team" group
├─ Data Sources:
│  ├─ Public Docs (All groups)
│  ├─ Internal Wiki (Support Team only)
│  └─ Customer Data (Managers only)
└─ Result: Support team sees public + internal, 
   Managers see all three

Configuration:

1. In Agent Settings → Data Sources

2. For each data source, set access control:

   • All Agent Users: Anyone who can use agent

   • Specific Groups Only: Restrict further

3. Agent will only retrieve from data sources user has access to

Permission Inheritance

Groups can inherit permissions from parent groups:

Organization
└─ Support Department
   ├─ Tier 1 Support
   │  └─ Inherits: Basic Support Agent
   └─ Tier 2 Support
      └─ Inherits: Basic + Advanced Support Agent

Setup:

1. Navigate to Administration → Groups

2. Create parent group: "Support Department"

3. Create child groups with parent relationship

4. Assign agents to parent group

5. Child groups inherit access automatically

Time-Based Access

Control when agents are available to groups:

Use Cases:

• Temporary contractor access

• Seasonal team expansion

• Trial periods

Configuration:

1. Agent Settings → Permissions → Advanced

2. For each group, set:

   • Start Date: When access begins

   • End Date: When access expires

   • Timezone: For scheduled access

3. Access automatically granted/revoked

Example:

Group: "Holiday Support Staff"
Agent: "Customer Support Agent"
Access: Dec 1, 2024 - Jan 15, 2025
Result: Agent appears/disappears automatically

Managing Permissions at Scale

API-Based Management

Automate permission management via API:

# Add group to agent
curl -X POST https://api.twig.so/api/ai-agent-managers/agent-123/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "group-456",
    "permission": "VIEW_AND_USE",
    "startDate": "2024-01-01",
    "endDate": "2024-12-31"
  }'

# Add users to group
curl -X POST https://api.twig.so/api/groups/group-456/members \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": ["user-1", "user-2", "user-3"],
    "role": "MEMBER"
  }'

Bulk Operations

Via UI:

1. Administration → Groups → Select multiple

2. Bulk Actions:

   • Add agents to multiple groups

   • Add users to multiple groups

   • Remove access in bulk

   • Export permission matrix

Via CSV Import:

AgentId,GroupId,Permission,StartDate,EndDate
agent-1,group-1,VIEW_AND_USE,2024-01-01,
agent-1,group-2,EDIT,2024-01-01,
agent-2,group-1,VIEW_AND_USE,2024-01-01,2024-12-31

SSO Group Sync (Enterprise)

Automatically sync groups from your identity provider:

Supported Providers:

• Azure AD / Microsoft Entra

• Okta

• Google Workspace

• OneLogin

• Custom SAML providers

Setup:

1. Navigate to Administration → SSO

2. Enable Group Sync

3. Map SSO groups to Twig groups:

   Azure AD Group "Sales Team" → Twig Group "Sales Team"
   Azure AD Group "Engineers" → Twig Group "Engineering Team"

4. Configure sync frequency:

   • Real-time (on login)

   • Hourly

   • Daily

5. Users automatically added/removed based on SSO groups

Monitoring & Auditing

Permission Audit Logs

Track all permission changes:

View Audit Logs:

1. Administration → Audit Logs

2. Filter by:

   • Event Type: "Permission Change"

   • Entity: Agent ID or Group ID

   • User: Who made the change

   • Date Range

Logged Events:

• Agent access type changed

• Group added/removed from agent

• User added/removed from group

• Permission level changed

• Data source restrictions modified

Example Log Entry:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "event": "GROUP_ADDED_TO_AGENT",
  "actor": "[email protected]",
  "agentId": "agent-123",
  "agentName": "Customer Support Agent",
  "groupId": "group-456",
  "groupName": "Support Team",
  "permission": "VIEW_AND_USE",
  "changes": {
    "before": "ORGANIZATION_WIDE",
    "after": "GROUP_RESTRICTED"
  }
}

Permission Reports

Generate reports on agent access:

Available Reports:

1. Agent Access Matrix

   • Which users can access which agents

   • Export to CSV/Excel

2. Group Membership Report

   • Users in each group

   • Group assignments per user

3. Permission Coverage

   • Users with no agent access

   • Agents with no assigned groups

4. Compliance Report

   • Access review status

   • Certification requirements

Generate Report:

Administration → Reports → Permission Reports
→ Select report type
→ Set filters and date range
→ Export or schedule

Security Best Practices

1. Principle of Least Privilege

✅ Do:

• Grant minimum necessary access

• Use group-restricted agents by default

• Regular access reviews (quarterly)

• Remove access promptly when users change roles

❌ Don't:

• Make all agents organization-wide

• Grant edit permissions broadly

• Skip access reviews

• Keep inactive users in groups

2. Separation of Duties

For sensitive agents:

• Separate view/use from edit permissions

• Require approval for permission changes

• Implement maker-checker for sensitive data access

3. Regular Audits

Monthly:

• Review group memberships

• Check for unused agent assignments

• Verify external user access

Quarterly:

• Full permission audit

• Recertify user access

• Update group structures

Annually:

• Review permission model

• Update access policies

• Archive old groups/agents

4. Data Classification

Align agent permissions with data sensitivity:

Data Classification	Agent Access	Approval Required
Public	Organization-wide	No
Internal	Group-restricted	Manager approval
Confidential	Private/Limited groups	Admin approval
Restricted	Named users only	C-level approval

Troubleshooting

User Can't See Agent

Check:

1. Is user in the organization?

2. Is agent set to Organization-Wide or Group-Restricted?

3. If Group-Restricted, is user in an assigned group?

4. Is user's account active?

5. Has user refreshed/logged out and back in?

Solution:

Administration → Groups → [Relevant Group] 
→ Members tab → Add User
→ Save → User logs out and back in

Group Not Appearing in Agent Settings

Check:

1. Does group exist and have active status?

2. Does group have at least one member?

3. Do you have permission to assign groups?

Solution:

• Ensure group is active

• Add at least one member to group

• Contact admin if permission issue

Permission Changes Not Taking Effect

Causes:

• Browser cache

• Session not refreshed

• Sync delay (SSO groups)

Solution:

1. Have user log out completely

2. Clear browser cache

3. Log back in

4. If SSO sync, wait for scheduled sync or trigger manual sync

Next Steps

• User Permissions & Roles - Detailed user permission model

• Group Management - Advanced group configuration

• SSO Integration - Set up SSO with group sync

• Audit Logs - Comprehensive audit logging