Roles & Grants
Understand how Discord roles map to SYNTHET permissions through grants, role priority, and scope management. Control exactly what each role can do across your server.
Role Synchronization
When you enable RBAC, SYNTHET automatically syncs your Discord roles into PolicyRoleBindings:
Automatic Sync
Every Discord role in your server becomes a PolicyRoleBinding. SYNTHET discovers roles by:
- •Scanning existing roles when RBAC is initialized
- •Detecting new roles created after RBAC is enabled
- •Marking deleted roles as archived (kept in history)
Role Information Stored
For each role, SYNTHET stores:
- •Role ID: Discord role's unique identifier
- •Role name: Current name (updated when Discord role is renamed)
- •Role color: Discord role's color for visual identification
- •Member count: How many users currently have the role
- •Priority: Evaluation order in permission checks
Sync Button: On the Roles tab, click "Sync Roles" to manually refresh role list from Discord. Useful after creating new roles.
Role Priority System
Roles are evaluated in priority order when checking permissions. Higher priority roles take precedence:
Priority Levels
Each role has a numeric priority (0-999, higher = evaluated first):
How Priority Works
When checking if a user can perform an action:
- 1.User's roles are sorted by priority (highest first)
- 2.For each role, check if it has a grant for the capability
- 3.If grant found, use that decision (ALLOW or DENY)
- 4.Don't check lower priority roles if a grant was found
Example Permission Flow
User has roles: Moderator (50), Member (10). Tries to ban someone.
1. Check Moderator (priority 50): Has "moderation.ban" grant = ALLOW → Result: User can ban
2. Stop checking (don't check Member role since we already decided)
Without the Moderator role, check Member (10) → No "moderation.ban" grant → Denied
Adjusting Priority
On the Roles tab, drag roles to reorder or click to edit priority number directly. Changes take effect immediately.
Capability Grants
Grants define what capabilities a role has permission to use:
Grant Components
Each grant consists of:
- •Capability: Which action (e.g., "moderation.ban", "economy.admin")
- •Effect: ALLOW or DENY
- •Scope (optional): Where permission applies (GUILD, CATEGORY, CHANNEL)
ALLOW vs DENY
ALLOW grants: Role can perform the capability
DENY grants: Role explicitly cannot perform the capability, even if a lower priority role allows it
Note: At the same priority, DENY takes precedence (fail-secure).
Viewing Grants
On the Roles tab, expand a role to see all its grants. Displays capability name, effect (ALLOW/DENY), and scope if applicable.
Scope Types
Scopes limit where a permission applies, allowing fine-grained channel-level control:
GUILD Scope
Permission applies server-wide. No channel restrictions.
Example: Role has GUILD-wide "moderation.ban" → can ban members anywhere
CATEGORY Scope
Permission applies only to channels in a specific category.
Example: Role has "moderation.delete_message" scoped to #support category → can delete messages only in that category's channels
CHANNEL Scope
Permission applies only to a specific channel.
Example: Role has "moderation.manage_channel" scoped to #logs → can only modify #logs channel settings
Scope Principle: Always use the most restrictive scope needed. Grant #support moderators channel permissions for #support only, not GUILD-wide.
Adding Grants to Roles
Configure what capabilities each role can use:
Grant Creation Workflow
- 1. Go to Roles tab
- 2. Click role to expand
- 3. Click "Add Grant" button
- 4. Select capability (searchable dropdown with all available capabilities)
- 5. Choose effect (ALLOW or DENY radio buttons)
- 6. Set scope (optional: GUILD, or select CATEGORY/CHANNEL)
- 7. Click "Create Grant"
Capability Searchable Dropdown
The capability selection uses SearchableSelect component:
- •Type to search by capability name (e.g., "ban", "mute", "economy")
- •Shows risk tier for each capability (LOW, MED, HIGH, CRITICAL)
- •Displays short description of what capability does
- •Click any result to select
Scope Selection
If you choose CATEGORY or CHANNEL scope:
- •CATEGORY: Multi-select dropdown shows all categories, choose one or more
- •CHANNEL: Multi-select dropdown shows all channels, choose one or more
Grant Creation Button
Green button with black text labeled "Create Grant". Disabled if required fields (capability, effect) aren't filled.
Conflict Resolution
When grants conflict, SYNTHET uses a clear resolution order:
Same Priority Conflict
If a role has both ALLOW and DENY grants for the same capability at the same priority:
DENY wins (fail-secure)
Example: Role has "moderation.ban" ALLOW (GUILD scope) and "moderation.ban" DENY (#spam channel scope). When banning in #spam, DENY takes effect.
Different Priority Conflict
If two of a user's roles have conflicting grants:
Higher priority role wins
Example: User has Admin (priority 80, grants "moderation.ban") and Member (priority 10, denies "moderation.ban"). Admin's ALLOW wins.
No Grant Found
If no role has a grant for the capability, the decision depends on defaultPublic setting. If true, capability is allowed. If false, capability is denied.
Best Practice: Keep grant structure simple. Avoid conflicting grants on the same role. Use priority-based role hierarchy instead.
System Roles vs Custom Roles
Some roles have special behavior in SYNTHET:
Server Owner
The member who created the Discord server. SYNTHET treats server owner specially:
- •Priority 1000 (highest possible, always checked first)
- •Can activate break-glass mode if misconfigured
- •Receives critical security alerts
Custom Discord Roles
Any role you create in Discord server settings. SYNTHET automatically syncs these and allows you to configure their grants independently.
Special Integration Roles
Some roles have automatic configuration:
- •@everyone: Default role all members have. Usually has minimal permissions
- •Bot roles: Roles assigned to SYNTHET bot and other bots. Configured via whitelist for bulk actions
Role Visual Indicators
The Roles tab shows visual cues for each role:
Role Color Indicators
Each role displays with its Discord role color. Makes it easy to identify roles visually, especially in large lists.
Member Count Badges
Shows how many members have each role. Helps identify high-impact roles.
Priority Labels
Priority number displayed next to role name. Easy to see evaluation order at a glance.
Grant Count Badges
Badge showing total number of grants for that role. Helps identify complex roles.
Archived Role Indicators
Deleted Discord roles are shown as "archived" (grayed out). Keeps history of permissions even after role is deleted.
Best Practices for Grants
- 1.Use clear role hierarchy: Create distinct roles (Owner, Admin, Moderator, Member) with clear priority order
- 2.Scope narrowly: Use CHANNEL or CATEGORY scope when possible, not GUILD-wide permissions
- 3.Avoid DENY: Instead of DENY grants, rely on not ALLOW-ing. Easier to understand.
- 4.Grant minimum needed: Don't grant CRITICAL capabilities unless absolutely necessary
- 5.Document grants: Keep notes on why each role has each grant for future reference
- 6.Test before applying: Use the Simulator to verify grant behavior before finalizing
- 7.Review regularly: Check role grants monthly. Remove unused grants.