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

# User Impersonation

> View the platform from the perspective of different user types

User impersonation allows administrators and support staff to view the AGO platform from the perspective of different user types. This feature is essential for testing access control configurations, troubleshooting user issues, and understanding the user experience across different permission levels.

## Overview

The impersonation feature enables:

* Testing agent access for different user types
* Debugging permission-related issues
* Previewing the user experience before deployment
* Validating access control rules

## How It Works

```mermaid theme={null}
flowchart TD
    A[Start Impersonation] --> B{User Type Selected?}
    B -->|Yes| C[Use Selected User Type]
    B -->|No| D[Use Highest Priority User Type]
    C --> E[Load Agents for User Type]
    D --> E
    E --> F{Agent Selected?}
    F -->|Yes| G[Use Selected Agent]
    F -->|No| H[Use Default Agent for User Type]
    G --> I[View as Impersonated User]
    H --> I
```

### User Type Priority

When no user type is explicitly selected, the system automatically uses the user type with the highest priority number. This ensures a consistent default experience.

### Agent Selection Logic

| Scenario                                  | Result                                       |
| ----------------------------------------- | -------------------------------------------- |
| Agent ID provided in request              | Uses specified agent (validates permissions) |
| No agent selected, permission has default | Uses permission's default agent              |
| No agent selected, no default configured  | Uses first available agent for user type     |

> **Note**: When both `agent_id` and `permission_id` are provided in a request, the system prioritizes `agent_id` and validates that the user has permission to access it.

## Using Impersonation

<Steps>
  <Step title="Access the Impersonation Selector">
    1. Navigate to the admin interface
    2. Locate the user type selector next to the agent dropdown
    3. Click to open the impersonation modal
  </Step>

  <Step title="Select a User Type">
    1. Choose from available user types in your organization
    2. The agent list will refresh to show only agents accessible to that user type
    3. Select a specific agent or use the default
  </Step>

  <Step title="View as the Selected User">
    Once impersonation is active:

    * All navigation and features reflect the selected user type's permissions
    * Agent responses will use the selected agent's configuration
    * Access controls are enforced as they would be for that user type
  </Step>

  <Step title="Exit Impersonation">
    * Select your original user type from the dropdown
    * Or click the "Exit Impersonation" button to return to your admin view
  </Step>
</Steps>

## Use Cases

### Testing Access Control Rules

Before deploying new access rules, use impersonation to verify:

1. Users see only their permitted agents
2. Knowledge sources are properly filtered
3. Tools are available as expected

### Troubleshooting User Issues

When a user reports access problems:

1. Impersonate their user type
2. Attempt to reproduce the issue
3. Identify missing permissions or misconfigured rules

### Validating Agent Configuration

After configuring a new agent:

1. Impersonate each user type that should have access
2. Verify the agent appears in their list
3. Test the agent's responses and tool availability

## API Reference

### Request Parameters

| Parameter       | Type | Required | Description                         |
| --------------- | ---- | -------- | ----------------------------------- |
| `permission_id` | UUID | No       | User type/permission to impersonate |
| `agent_id`      | UUID | No       | Specific agent to use               |

### Behavior Rules

* If `agent_id` is provided without `permission_id`, the system validates access before proceeding
* If both are provided, `agent_id` takes precedence
* If neither is provided, defaults are used based on priority

## Best Practices

### Security Considerations

* Impersonation is logged for audit purposes
* Only administrators can access impersonation features
* Impersonated actions are marked in system logs

### Testing Workflow

1. **Create test user types** for each permission level
2. **Document expected access** for each user type
3. **Test systematically** through all user types after configuration changes
4. **Verify default behaviors** work correctly

### Common Pitfalls

* Forgetting to exit impersonation before making admin changes
* Not testing all user types after permission changes
* Assuming admin access rules apply to impersonated views

## Troubleshooting

<AccordionGroup>
  <Accordion title="Issue: No agents appear for selected user type">
    **Solutions:**

    1. Verify the user type has agents linked via permissions
    2. Check that linked agents are active
    3. Review access control rules for the user type
  </Accordion>

  <Accordion title="Issue: Wrong agent selected by default">
    **Solutions:**

    1. Check the default agent setting on the permission
    2. Verify priority numbers are set correctly
    3. Ensure the expected default agent is active
  </Accordion>

  <Accordion title="Issue: Impersonation doesn't reflect expected permissions">
    **Solutions:**

    1. Clear browser cache and refresh
    2. Verify the permission configuration is saved
    3. Check for conflicting access control rules

    ***
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Access Control Rules](./access-control-rules) - Configure who can access what
* [Agent Permissions](./agent-permissions) - Link agents to user types
* [Agents](../agent/agents) - Agent configuration details