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

# Permissions & Roles

> Understand Veronica's permission system and role hierarchy.

# Permissions & Roles

Veronica uses a multi-layered permission system that combines Discord's native permissions, role hierarchy, and custom bot authority to ensure secure and flexible access control.

## Permission Layers

<Steps title="Authority Mapping Workflow">
  <Step title="Server Owner">
    **Highest Authority** - Bypasses all permission checks.
    <Check>Ownership verified.</Check>
  </Step>

  <Step title="Discord Permissions">
    **Native Discord Permissions** - Standard Discord permission system.
    <Check>Role-based access confirmed.</Check>
  </Step>

  <Step title="Bot Authority">
    **Custom Permission Layer** - Veronica-specific fake permissions.
    <Check>Virtual authority engaged.</Check>
  </Step>

  <Step title="Role Hierarchy">
    **Position-Based Checks** - Role position in server settings.
    <Check>Hierarchy audit complete.</Check>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Bot Authority" icon="code-branch" href="/configuration/permissions#bot-authority-system">
    Learn how to grant specific bot permissions without Discord roles.
  </Card>

  <Card title="Moderation" icon="gavel" href="/resources/commands">
    See how permissions apply to the full suite of moderation commands.
  </Card>
</CardGroup>

## Permission Mapping

Veronica maps its commands to Discord permissions:

| Command Category    | Required Permission |
| :------------------ | :------------------ |
| Ban, Unban, Hardban | `Ban Members`       |
| Kick                | `Kick Members`      |
| Mute, Timeout       | `Moderate Members`  |
| Purge, Clear        | `Manage Messages`   |
| Lock, Unlock        | `Manage Channels`   |
| Role Management     | `Manage Roles`      |
| Auto-Mod, Settings  | `Administrator`     |

## Role Hierarchy

### How It Works

```mermaid theme={null}
graph TD
    A[Command Executed] --> B{Is Server Owner?}
    B -->|Yes| Z[✅ Allowed]
    B -->|No| C{Has Discord Permission?}
    C -->|No| X[❌ Denied]
    C -->|Yes| D{Has Bot Authority?}
    D -->|No| E{Check Hierarchy}
    D -->|Yes| Z
    E -->|Moderator Role < Target Role| X
    E -->|Moderator Role > Target Role| F{Bot Role > Target Role?}
    F -->|No| X
    F -->|Yes| Z
```

### Example Scenarios

<AccordionGroup>
  <Accordion title="Scenario 1: Moderator Bans Member">
    **Setup:**

    * Moderator has `Ban Members` permission
    * Moderator role: Position 5
    * Target role: Position 3
    * Bot role: Position 10

    **Result:** ✅ **Allowed** - Moderator is higher than target, bot is higher than both
  </Accordion>

  <Accordion title="Scenario 2: Moderator Tries to Ban Admin">
    **Setup:**

    * Moderator has `Ban Members` permission
    * Moderator role: Position 5
    * Admin role: Position 8
    * Bot role: Position 10

    **Result:** ❌ **Denied** - Moderator cannot act on higher roles
  </Accordion>

  <Accordion title="Scenario 3: Bot Role Too Low">
    **Setup:**

    * Moderator has `Ban Members` permission
    * Moderator role: Position 5
    * Target role: Position 3
    * Bot role: Position 2

    **Result:** ❌ **Denied** - Bot cannot manage roles above it
  </Accordion>
</AccordionGroup>

## Bot Authority System

### Fake Permissions

Grant Veronica-specific permissions without Discord permissions:

<CodeGroup>
  ```bash Grant Fake Permission theme={null}
  /fakeperm add user:@Member permission:manage_jail
  ```

  ```bash Remove Fake Permission theme={null}
  /fakeperm remove user:@Member permission:manage_jail
  ```

  ```bash List Fake Permissions theme={null}
  /fakeperm list user:@Member
  ```
</CodeGroup>

**Available Fake Permissions:**

* `manage_jail` - Use jail commands
* `manage_automod` - Configure Auto-Mod
* `manage_economy` - Manage economy settings
* `manage_leveling` - Configure leveling system

### Active Sessions

Temporary elevated access for specific users:

```bash theme={null}
/session create user:@Member duration:1h permissions:administrator
```

**Use Cases:**

* Temporary moderator access
* Event management
* Trial moderator periods
* Emergency permissions

### Bot Accounts

Multi-user bot control system:

```bash theme={null}
/botaccount add user:@Developer
/botaccount permissions user:@Developer level:admin
```

## Permission Best Practices

<CardGroup cols={2}>
  <Card title="Principle of Least Privilege" icon="shield">
    Only grant permissions that are absolutely necessary for a role's responsibilities.
  </Card>

  <Card title="Role Separation" icon="layer-group">
    Create distinct roles for different staff levels (Helper, Moderator, Admin).
  </Card>

  <Card title="Regular Audits" icon="clipboard-check">
    Periodically review role permissions and remove unnecessary access.
  </Card>

  <Card title="Bot Position" icon="arrow-up">
    Keep Veronica's role near the top of your role list for maximum functionality.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command says 'Missing Permissions'">
    **Solutions:**

    * Verify you have the required Discord permission
    * Check your role position vs. target role
    * Ensure bot role is above target role
    * Confirm you're not trying to moderate equal/higher roles
  </Accordion>

  <Accordion title="Bot can't assign roles">
    **Solutions:**

    * Move bot role above the roles it needs to manage
    * Verify bot has `Manage Roles` permission
    * Check if roles are managed by integrations (cannot be assigned)
  </Accordion>

  <Accordion title="Auto-Mod not working on certain users">
    **Solutions:**

    * Check if users have exempt roles
    * Verify users aren't whitelisted
    * Ensure bot role is above user roles
  </Accordion>
</AccordionGroup>

<Warning>
  **Critical:** Never give untrusted users `Administrator` permission or access to bot authority commands. These bypass most security checks.
</Warning>