Quick Start
1
Define a group, use it in a channel
gateway.yaml
2
Nest groups and share across channels
gateway.yaml
How It Works
Expansion happens once at config load, before validation and admission, so every channel admits from the same definition.Configuration
Each group value can take three shapes.- List
- Comma string
- Env-backed
Fail-Closed Behaviour
A bad reference stops the gateway instead of silently widening or narrowing access.Common Patterns
One team, three channels
One team, three channels
Reference
group:team from Telegram, Discord and Slack. Remove a person from team once and they lose access everywhere.Env-backed groups
Env-backed groups
Keep ids out of the file with
admins: ["${ADMINS}"] and set ADMINS=111,222.Nested roles
Nested roles
Put
group:admins inside team so admins are automatically team members.Scope
expand_access_groups (Python)
Pure, zero-dependency expansion used by the gateway loader.
Best Practices
Define once, reference everywhere
Define once, reference everywhere
Never re-paste raw ids into each channel — they drift.
Use simple group names
Use simple group names
Lowercase names such as
admins or on_call are easy to spot in reviews.Model roles with nesting
Model roles with nesting
Build hierarchies like
admins ⊂ oncall ⊂ team.Keep the strict default
Keep the strict default
Pair groups with
unknown_user_policy: "deny". See Channel Security.Related
Bot Gateway
Channel Security settings
Bot Security
Broader security posture
Channels Gateway
Shared allowlist surface
Gateway Config Migration
Gateway keys inventory