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.

Portal Access and Agent Permissions

Assigning permissions to a user determines which agents they can use. It does not, by itself, authorize that user to enter the client portal.

For portals using Clerk sign-in, non-administrator accounts must also match an active email access rule: a specific email address, their email domain, or the wildcard domain *. Staff and superadmin accounts are exempt from this portal entry check.

For example, a user can have the seller permission and still receive 401 Unauthorized when opening the portal if no active email rule matches them. A direct agent assignment does not replace that rule either.

This portal entry check is separate from the agent access checks below and from widget authentication.

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.

The public-agent shortcut requires an active agent. Staff and superadmins can access inactive agents for testing, and an agent assigned as a permission’s default can remain accessible through that permission. To withdraw access, also remove default-agent assignments; do not rely on the status alone.

How Access Is Determined

Staff and superadmins can access any existing agent. Other users can call an active public agent or an agent available through one of their active permissions. A missing agent returns 404 Not Found; an existing agent the user cannot access returns 403 Forbidden.

For each active permission, AGO includes its active linked agents and its configured default agent. Direct user assignments and agents from matching email/domain rules supplement a permission group only when that group already has a default agent, an active linked agent, or an active public agent.

A direct agent assignment or an agent-only email rule is therefore not sufficient for a user with no active permissions. For predictable access, grant an active permission and link the intended agents to it.

Access source	Requirement
Public agent	Agent is public and active
Permission-linked agent	User has the active permission and the linked agent is active
Permission default	User has the active permission that names this default agent
Direct or email-rule agent	Agent is active and supplements a qualifying permission group as described above

Custom permissions control customer-facing agents and content. They do not grant staff, viewer, or organization-management roles.

---

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 the user does not explicitly select an agent, AGO uses the selected permission if it belongs to the user. If no permission was selected, AGO chooses the user’s highest-priority active permission.

For that permission:

1. Use its configured default agent, if present.
2. Otherwise, use its first active linked agent, ordered by display order and then name.
3. If neither exists, no default agent is resolved from that permission. AGO does not then fall back to an agent from an access rule.

If a supplied permission cannot be resolved, AGO checks the available permission groups for an agent instead. Configure a default on each permission to make the intended choice explicit.

---

Configuring Permissions

Creating Permissions

1. Navigate to AI Studio → Permissions
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

Granting Permissions with Rules

1. Open AI Studio → Permissions.
2. Choose Email-based permissions for email/domain rules, JWT-based permissions for JWT claims, or API-based permissions for data returned by your configured API.
3. Create a rule and select the permissions it grants.
4. Link the intended agents to those permissions and test with a non-admin account.

Open Settings → User Management → Users and select a user to inspect the permissions displayed on their profile. This profile does not have permission-editing or Direct Agents tabs.

Access Control Rules

Matching rules add permissions cumulatively; a higher-priority rule does not revoke grants from another matching rule. Link agents to the granted permissions rather than relying on an additional-info rule’s agent assignment.

These rules determine agent access after entering the application. They do not replace the portal entry check described above. See Access Control Examples for JWT rule setup.

---

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 non-admin accounts: Check the actual authentication and permission rules
• Check all pathways: A user might have access through unexpected paths
• Review rule conditions: Access rules can grant unexpected access

---

Troubleshooting

Issue: Client portal returns 401 despite assigned permissions

A non-administrator signing in through Clerk needs an active email access rule in addition to their agent permissions. Assigning a permission in the user’s profile does not create that rule.

1. Open Agent Permissions → Email-based permissions.
2. In Specific Emails, add an active rule for the user’s exact sign-in email, or verify that an active domain rule already covers them.
3. Save the rule and retry opening the portal. Portal access rules are cached for up to one minute.

Use a specific email rule when granting access to one person. Permissions determine which agents they can use once admitted to the portal.

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 which permissions the matching access rules grant
4. Test with a non-admin account using the intended authentication method

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. Verify the rule grants an active permission linked to the agent
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