Access Groups

Define a set of senders once and reference it from any channel's allow/block list.

Access groups let you name a set of senders once and reference it from any channel — one definition, one revoke point.

Quick Start

1. Define a group, use it in a channel

   agents:
     assistant: { instructions: "Help the user." }
   
   access_groups:
     admins: ["111", "222"]
   
   channels:
     telegram:
       token: ${TELEGRAM_BOT_TOKEN}
       allowed_users: ["group:admins"]   # expands to ["111", "222"]

   praisonai gateway start --config gateway.yaml

2. Nest groups and share across channels

   agents:
     assistant: { instructions: "Help the user." }
   
   access_groups:
     admins: ["111", "222"]
     team:   ["group:admins", "333"]   # groups may nest
   
   channels:
     telegram:
       token: ${TELEGRAM_BOT_TOKEN}
       allowed_users: ["group:team"]   # expands to ["111", "222", "333"]
     discord:
       token: ${DISCORD_BOT_TOKEN}
       allowed_users: ["group:admins"] # expands to ["111", "222"]
       blocklist:     ["999"]

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.

access_groups:
  admins: ["111", "222"]

access_groups:
  admins: "111, 222"

# ADMINS=111,222
access_groups:
  admins: ["${ADMINS}"]

channels:
  discord:
    token: ${DISCORD_BOT_TOKEN}
    allowed_users: ["group:admins"]   # ["111", "222"]

Fail-Closed Behaviour

A bad reference stops the gateway instead of silently widening or narrowing access.

Gateway config validation failed (gateway.yaml):
  - channels.telegram.allowed_users: Unknown access group: 'nope'

On hot-reload, a bad reference keeps the last-known-good config.

Common Patterns

Scope

Best Practices

Related