> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```mermaid theme={null}
flowchart TD
    A[User selects an agent] --> B{Agent exists?}
    B -->|No| N404[404 Not Found]
    B -->|Yes| C{Staff or superuser?}
    C -->|Yes| OK[Access granted]
    C -->|No| D{Agent is public<br/>AND status = active?}
    D -->|Yes| OK
    D -->|No| E{Agent linked to<br/>one of user's permissions?}
    E -->|Yes| OK
    E -->|No| F{Agent is the default agent<br/>of one of user's permissions?}
    F -->|Yes| OK
    F -->|No| G{Agent directly<br/>linked to user?}
    G -->|Yes| OK
    G -->|No| H{Agent linked to<br/>a matching access rule?}
    H -->|Yes| OK
    H -->|No| DENY[403 Forbidden]
```

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

```mermaid theme={null}
flowchart TD
    A[No Agent Selected] --> B{Permission Selected?}
    B -->|Yes| C[Use Permission's Default Agent]
    B -->|No| D[Use Highest Priority Permission]
    D --> E{Has Default Agent?}
    E -->|Yes| F[Use That Default Agent]
    E -->|No| G[Use First Linked Agent]
    G --> H{Still No Agent?}
    H -->|Yes| I[Use First Access Rule Agent]
    C --> J[Agent Resolved]
    F --> J
    I --> J
```

### 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](./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:

```javascript theme={null}
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](./impersonate), 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](../api/public-api-v1) - 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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

    ***
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Access Control Rules](./access-control-rules) - Detailed rule configuration
* [Access Control Examples](./access-control-examples) - Common access patterns
* [User Impersonation](./impersonate) - Test permission configurations
* [Agents](../agent/agents) - Agent configuration options