# 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:

```bash
# 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:**

```csv
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:**

```json
{
  "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](/product/administration/user-permissions.md) - Detailed user permission model
* [Group Management](https://github.com/thrivapp/twig-help-docs/blob/staging/administration/group-management.md) - Advanced group configuration
* [SSO Integration](https://github.com/thrivapp/twig-help-docs/blob/staging/security/sso-integration.md) - Set up SSO with group sync
* [Audit Logs](https://github.com/thrivapp/twig-help-docs/blob/staging/administration/audit-logs.md) - 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 https://help.twig.so/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.