Agent Permissions & Access Control

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

Overview

Control which users can view, use, and edit agents.

Permission levels:

• Organization-Wide: All users in org can access
• Group-Restricted: Only members of assigned groups
• Private: Only creator and admins

Configured: Agent Settings → Permissions tab

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": "admin@company.com",
  "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

---

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 /dev/product/administration/agent-permissions.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.