Agent Permissions

Control which users can access which agents

Agent permissions control which users can access which agents. This system ensures users only see and interact with agents appropriate for their role, department, or access level.

Overview

The permission system determines agent access through multiple pathways:

• Public agent flag
• Direct user-to-agent links
• Permission-based access
• Access control rules
• System requirements

Understanding these pathways is essential for configuring proper access control.

Public Agents

Toggle Make this agent public in an agent’s Access Control tab to let every user call it — including non-authenticated users — regardless of permissions or rules. Use this for agents meant to be available to everyone (for example, a general help agent) instead of linking the agent to every permission.

An inactive agent is never accessible, even when marked public.

How Access Is Determined

The system evaluates checks in order. The first one that matches grants access. If none match, the request is rejected with a 403 Forbidden error.

When the 403 Forbidden error is raised

Users see a Forbidden error when every check above fails:

• They are not staff or superuser.
• The agent is not marked public (or the agent is inactive).
• None of the user’s permissions list the agent or set it as the default agent.
• The agent is not directly linked to the user.
• No access control rule that matches the user links to the agent.

A 404 Not Found is returned instead if the agent ID does not exist.

Access Pathways Explained

Pathway	Description	Use Case
Direct Link	User explicitly linked to agent	VIP users, specific assignments
Permission Linked	User’s permission includes agent	Role-based access
Access Rule	User matches access rule criteria	Dynamic, attribute-based access
System Requirements	Special system-level access	Internal agents, admin-only

Important: A user needs only ONE pathway to grant access. Pathways are evaluated with OR logic.

---

Permissions and User Types

Permissions (also called “user types”) group users with similar access needs. Each permission can be linked to multiple agents.

Permission Configuration

Field	Description
name	Display name for the permission
priority	Number determining default selection order
agents	List of agents this permission grants access to
default_agent	Agent shown by default for this permission

How Permissions Work

1. User Creation: User is assigned one or more permissions
2. Agent Discovery: System compiles agents from all user’s permissions
3. Display: User sees combined list of accessible agents
4. Selection: Default agent is determined by permission priority

---

Default Agent Selection

When a user doesn’t explicitly select an agent, the system determines which agent to show using this logic:

Priority Order

1. Explicitly selected permission’s default agent
2. Highest priority permission’s default agent
3. First agent linked to highest priority permission
4. First agent from user’s access rules

---

Configuring Permissions

Creating Permissions

1. Navigate to Settings → User Management → Permissions tab
2. Click Create Permission or edit existing
3. Configure fields:
   • Name and description
   • Priority number (higher = selected first)
   • Linked agents
   • Default agent selection
4. Click Save

Assigning Permissions to Users

1. Navigate to Settings → User Management → Users tab
2. Select the user to configure
3. Go to the Permissions tab
4. Add or remove permissions as needed
5. Click Save

---

Direct Agent Links

For special cases, link users directly to agents without going through permissions.

Use Cases

• Executive access to specific agents
• Testing access for QA users
• Temporary project-based access

Configuration

1. Navigate to Settings → User Management → Users tab
2. Select the user
3. Go to the Direct Agents tab
4. Add specific agents to grant direct access
5. Click Save

Note: Direct links take precedence but don’t override permission-based default agent selection.

---

Access Control Rules

Access rules provide dynamic, attribute-based access. See Access Control Rules for detailed configuration.

How Rules Interact with Permissions

Scenario	Result
User has permission + matching rule	Access via both pathways
User has permission, no matching rule	Access via permission
User has no permission, matching rule	Access via rule
User has neither	No access

---

Widget Permission Override

When embedding the widget on third-party sites, you can dynamically assign a permission to a user by passing the X-Widget-Permission header in widget requests:

fetch('https://api.example.com/api/endpoint', {
    headers: {
        'X-User-Anon-Id': 'unique-widget-instance-id',
        'X-Widget-Permission': 'enterprise'
    }
})

The permission is applied only if it is marked as Public in its configuration. This lets you control which permissions can be set by the widget client.

---

Impersonation and Permissions

When using impersonation, the agent list updates to show only agents accessible to the selected permission.

Impersonation Flow

1. Select a permission to impersonate
2. Agent list refreshes to show:
   • Agents linked to the selected permission
   • Agents from access rules applicable to that permission
   • Direct-linked agents (if any)

---

API Reference

For programmatic access to permissions and user management, see:

• Public API v1 Reference - Permission and user management

---

Best Practices

Permission Design

• Group by role: Create permissions matching organizational roles
• Use meaningful priorities: Higher priority for more common roles
• Set defaults thoughtfully: Default agent should serve most use cases

Access Management

• Prefer permissions over direct links: Easier to maintain at scale
• Use access rules for dynamic access: When access depends on user attributes
• Audit regularly: Review who has access to which agents

Troubleshooting Access

• Test with impersonation: Verify access before user complaints
• Check all pathways: A user might have access through unexpected paths
• Review rule conditions: Access rules can grant unexpected access

---

Troubleshooting

Issue: User can't see expected agent

Problem: Agent doesn’t appear in user’s list.

Solutions:

1. Verify agent is active (not disabled)
2. Check user’s permissions include the agent
3. Review access rules that might exclude the agent
4. Test with impersonation to see user’s view

Issue: Wrong default agent selected

Problem: User sees unexpected agent as default.

Solutions:

1. Check permission priorities (highest number wins)
2. Verify default agent is set on the correct permission
3. Ensure user doesn’t have higher-priority permissions

Issue: User sees too many agents

Problem: User has access to agents they shouldn’t see.

Solutions:

1. Audit user’s permissions for unnecessary links
2. Review access rules for overly broad conditions
3. Check for direct agent links
4. Consider using more restrictive permissions

Issue: Access rule not granting access

Problem: User matches rule but can’t access agent.

Solutions:

1. Verify rule condition syntax is correct
2. Check rule is active (not disabled)
3. Ensure agent is linked to the rule
4. Test rule conditions with actual user attributes

---

Related Documentation

• Access Control Rules - Detailed rule configuration
• Access Control Examples - Common access patterns
• User Impersonation - Test permission configurations
• Agents - Agent configuration options