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

# Access Control Examples

> Real-world examples of access control rules with JWT authentication

This guide provides real-world examples of using access control rules with JWT authentication and additional info fields.

> **ℹ️ NOTE**: Access control rules are managed at **Settings** → **User Management** → **Access Control** → **Additional Info** tab.

## Complete Workflow: JWT to Permissions

<Steps>
  <Step title="Configure JWT Field Mappings">
    In your backend configuration, configure which JWT fields to extract:

    ```json theme={null}
    {
      "widget_jwt_fields_mapping": [
        {
          "jwt_field": "department",
          "label": "Department"
        },
        {
          "jwt_field": "user_metadata.subscription",
          "label": "Subscription Tier"
        },
        {
          "jwt_field": "location.region",
          "label": "Region"
        },
        {
          "jwt_field": "employee.id",
          "label": "Employee ID"
        }
      ]
    }
    ```
  </Step>

  <Step title="User Authenticates with JWT">
    When a user authenticates via the widget with a JWT token:

    **JWT Payload Example:**

    ```json theme={null}
    {
      "sub": "user123",
      "email": "john.doe@company.com",
      "department": "IT",
      "user_metadata": {
        "subscription": "enterprise"
      },
      "location": {
        "region": "europe"
      },
      "employee": {
        "id": "EMP456"
      }
    }
    ```

    **Resulting additional info fields:**

    ```json theme={null}
    {
      "jwt_claims": { /* full JWT payload */ },
      "jwt_sub": "user123",
      "jwt_iss": "https://auth.company.com",
      "jwt_extracted_fields": {
        "Department": "IT",
        "Subscription Tier": "enterprise",
        "Region": "europe",
        "Employee ID": "EMP456"
      },
      "department": "IT",
      "subscription_tier": "enterprise",
      "region": "europe",
      "employee_id": "EMP456"
    }
    ```
  </Step>

  <Step title="Create Permission Rules">
    Create additional info rules that leverage the flattened fields:
  </Step>
</Steps>

#### Example 1: Department-Based Access

**Grant IT support permissions to IT department:**

```json theme={null}
{
  "name": "IT Department Access",
  "conditions": [
    {
      "key": "department",
      "value": "IT",
      "negate": false
    }
  ],
  "permission_ids": ["it-support-permission-uuid"],
  "agent_ids": ["it-helpdesk-agent-uuid"],
  "priority": 100,
  "is_active": true
}
```

#### Example 2: Subscription Tier Access

**Grant premium features to enterprise subscribers:**

```json theme={null}
{
  "name": "Enterprise Features",
  "conditions": [
    {
      "key": "subscription_tier",
      "value": "enterprise",
      "negate": false
    }
  ],
  "permission_ids": ["enterprise-features-uuid"],
  "agent_ids": ["enterprise-agent-uuid"],
  "priority": 90,
  "is_active": true
}
```

#### Example 3: Regional Compliance

**Grant GDPR-compliant access to European users:**

```json theme={null}
{
  "name": "European Users - GDPR Compliant",
  "conditions": [
    {
      "key": "region",
      "value": "europe",
      "negate": false
    }
  ],
  "permission_ids": ["gdpr-compliant-permission-uuid"],
  "priority": 80,
  "is_active": true
}
```

#### Example 4: Combined Conditions

**Grant special access to enterprise users in Europe:**

```json theme={null}
{
  "name": "Enterprise Europe Premium",
  "conditions": [
    {
      "key": "subscription_tier",
      "value": "enterprise",
      "negate": false
    },
    {
      "key": "region",
      "value": "europe",
      "negate": false
    }
  ],
  "permission_ids": ["enterprise-eu-permission-uuid"],
  "agent_ids": ["eu-premium-agent-uuid"],
  "priority": 95,
  "is_active": true
}
```

#### Example 5: Negative Matching

**Grant basic access to non-trial users:**

```json theme={null}
{
  "name": "Non-Trial Users",
  "conditions": [
    {
      "key": "subscription_tier",
      "value": "trial",
      "negate": true
    }
  ],
  "permission_ids": ["full-access-uuid"],
  "priority": 70,
  "is_active": true
}
```

## Use Case Scenarios

### Scenario 1: SaaS Platform with Tiered Access

**Business Requirements:**

* Free users: Basic agent, limited features
* Pro users: Advanced agent, full features
* Enterprise users: Premium agent, priority support, custom features

**Implementation:**

1. Configure JWT to extract `subscription_plan` field
2. Create three rules:

**Free tier** (negate paid tiers):

```json theme={null}
{
  "name": "Free Tier Users",
  "conditions": [
    {"key": "subscription_plan", "value": "pro", "negate": true},
    {"key": "subscription_plan", "value": "enterprise", "negate": true}
  ],
  "permission_ids": ["basic-permission-uuid"],
  "agent_ids": ["basic-agent-uuid"],
  "priority": 10
}
```

**Pro tier:**

```json theme={null}
{
  "name": "Pro Users",
  "conditions": [
    {"key": "subscription_plan", "value": "pro", "negate": false}
  ],
  "permission_ids": ["pro-permission-uuid"],
  "agent_ids": ["advanced-agent-uuid"],
  "priority": 50
}
```

**Enterprise tier:**

```json theme={null}
{
  "name": "Enterprise Users",
  "conditions": [
    {"key": "subscription_plan", "value": "enterprise", "negate": false}
  ],
  "permission_ids": ["enterprise-permission-uuid"],
  "agent_ids": ["premium-agent-uuid"],
  "priority": 100
}
```

### Scenario 2: Multi-Tenant B2B Platform

**Business Requirements:**

* Each client organization has different feature sets
* Internal employees get admin access
* Partners get limited access

**Implementation:**

**Internal employees:**

```json theme={null}
{
  "name": "Internal Employees",
  "conditions": [
    {"key": "organization_type", "value": "internal", "negate": false}
  ],
  "permission_ids": ["admin-permission-uuid"],
  "priority": 100
}
```

**Partner organizations:**

```json theme={null}
{
  "name": "Partner Access",
  "conditions": [
    {"key": "organization_type", "value": "partner", "negate": false}
  ],
  "permission_ids": ["partner-permission-uuid"],
  "agent_ids": ["partner-agent-uuid"],
  "priority": 50
}
```

**Client-specific features:**

```json theme={null}
{
  "name": "Client ABC - Advanced Features",
  "conditions": [
    {"key": "organization_id", "value": "client-abc", "negate": false}
  ],
  "permission_ids": ["advanced-features-uuid"],
  "priority": 80
}
```

### Scenario 3: Role-Based Access Control

**Business Requirements:**

* Support agents: Access to support tools
* Managers: Access to analytics and reporting
* Admins: Full system access

**Implementation:**

**Support agents:**

```json theme={null}
{
  "name": "Support Agents",
  "conditions": [
    {"key": "role", "value": "support", "negate": false}
  ],
  "permission_ids": ["support-tools-uuid"],
  "agent_ids": ["support-agent-uuid"],
  "priority": 60
}
```

**Managers:**

```json theme={null}
{
  "name": "Manager Access",
  "conditions": [
    {"key": "role", "value": "manager", "negate": false}
  ],
  "permission_ids": ["manager-permission-uuid", "analytics-uuid"],
  "priority": 80
}
```

**Admins:**

```json theme={null}
{
  "name": "Admin Access",
  "conditions": [
    {"key": "role", "value": "admin", "negate": false}
  ],
  "permission_ids": ["admin-permission-uuid", "full-access-uuid"],
  "priority": 100
}
```

## Testing Your Rules

### Method 1: Verify via Admin UI

Check a user's profile in the admin panel to see what fields are available for rule matching:

1. Navigate to **Settings** → **User Management** → **Users**
2. Select the user you want to inspect
3. Review the **Additional Info** section to see available fields and values
4. Confirm the fields match what your rules expect

### Method 2: Test with a Sample User

To verify a rule works as expected:

1. Create or identify a test user whose additional info matches your rule conditions
2. Log in as that user (or use [impersonation](../users/impersonate) if available)
3. Confirm the user sees the expected agents, knowledge sources, and features based on the applied permissions

## Best Practices

1. **Use Descriptive Names**: Make rule names clear and specific
2. **Set Appropriate Priorities**: Higher priority for more specific rules
3. **Test in Development**: Verify rules work before deploying to production
4. **Document Business Logic**: Keep track of why each rule exists
5. **Regular Audits**: Review and update rules periodically
6. **Use Consistent Naming**: Stick to snake\_case for field names
7. **Monitor Performance**: Watch for rules that may need optimization

## Troubleshooting

<AccordionGroup>
  <Accordion title="Rule Not Applying">
    1. Check if the rule is active
    2. Verify the user has the expected additional info fields
    3. Check field names match exactly (case-sensitive after normalization)
    4. Ensure all conditions in the rule match (AND logic)
    5. Check if a higher-priority rule might be overriding
  </Accordion>

  <Accordion title="Field Not Found">
    1. Verify JWT field mapping is configured correctly
    2. Check JWT actually contains the expected field
    3. Check the user's additional info fields in **Settings** → **User Management** → **Users**
    4. Ensure field name normalization is working correctly
  </Accordion>

  <Accordion title="Unexpected Permissions">
    1. Check all active rules that might apply
    2. Remember rules are cumulative (user gets ALL matching permissions)
    3. Review priority settings
    4. Check for wildcard domain rules that might apply
  </Accordion>
</AccordionGroup>