#Permissions & Authorization

botmux permissions answer two questions: who can talk to the bot (canTalk) and who can change session state (canOperate — /cd, /restart, /close, card buttons). There are several authorization layers, from "a few named admins" to "the whole group can ask freely". This page covers all of them in one place.

#Authorization layers

Notes:

• A bot created through normal onboarding always has its owner in allowedUsers, so it is a restricted bot by default — only listed people can use it.
• Team-trust legs (same-team peer bots / team bots / platform team members) grant talk only; see Roles & Teams.
• Field-level reference: bots.json · Permissions and authorization.

#Common operations

Only owners / admins (allowedUsers) can run /grant, /revoke, on-call toggles, and management commands such as /card, /cot, /mention-mode. Graduated guests can only talk.

#Being added to a group is not authorization

Pulling the bot into a group does not write any allowlist entry. When the bot receives the "added to chat" event it does not open up talk access for that group:

• On a restricted bot (one with an owner / allowlist — every bot created via onboarding is such a bot), a non-listed member @-mentioning the bot is refused, and the bot automatically sends the owner a grant request card. The owner approves in one click (after which the original message is replayed automatically, so the person doesn't need to resend it).
• Only a fully unconfigured open-mode bot can be used by anyone (operate rights included). That is a fallback state, not something "being added to a group" grants.
• "Auto-start when added to a group" (autoStartOnGroupJoin) is not an authorization either: it has its own gate — the group must contain at least one allowedUsers member before the bot auto-starts a session.

Precisely controlling who can add the bot to groups belongs to the Lark platform side (app availability scope / who can add bots); see the FAQ at the bottom.

#Block list blockedUsers

The block list is a sender-dimension global deny, maintained on the Bot config page (Dashboard Bot Config), with a quick "block" action available in the group-member modal as well:

• It applies to both groups and DMs; a blocked person is denied in on-call groups, whole-group-open groups, and team groups alike.
• The deny leg runs before every allow leg — on-call, whole-group open, guest grants, team trust — so there is no "works again in another group" escape.
• When a blocked person is rejected, no grant request card is sent to the owner (no approval-spam from someone you explicitly blocked).
• Owners / admins cannot be blocked — the write entry refuses it (self-lockout guard).
• The block list governs talk access only; the message listener feature (rules that make a bot watch messages automatically) has its own matching configuration and is not affected by it.

#Grant request cards

On a restricted bot, when an unauthorized person explicitly @-mentions the bot in a group and the talk gate blocks them, a request card is sent to the owner by default (autoGrantRequestCards, on by default; can be turned off in Bot config, after which messages are blocked silently).

• On the request card the owner can Grant talk in this group or Deny, adjusting quota and duration right on the card.
• The owner-initiated @bot /grant @someone card additionally offers Grant global talk (effective in any group).
• After approval, the message that triggered the request is replayed into the session automatically; the requester doesn't need to @ again.
• Pending requests are throttled, so one person cannot spam cards.
• A rejected DM (p2p) is silent by default: there is no owner present in that DM, and replying with a card would go to the stranger themselves (unusable for them, and it would expose the owner), so no card is sent.
• Forward request cards to the owner's DM (grantRequestToOwnerDm, off by default): when enabled and no admin in the conversation can click the card, the card goes to the primary owner's DM instead — both when no admin is in the group (e.g. autoInviteOwnerOnGroupAdd is off and the owner stays out) and when a DM is rejected. The requester only gets a neutral acknowledgement that does not reveal the owner; after the owner approves or denies, the outcome is posted back to the original conversation; once the quota runs out, the next message re-applies automatically. If an admin is in the group, or the member lookup fails, the card is posted in the group as before. DM forwarding has an extra per-owner cap (20 cards per hour; failed sends do not count). Over the cap or on a send failure no card is posted (the group is already known to have no admin, so an in-group card would be one nobody can click); the next message retries. The group path lists chat members on every request (60-second cache); if the app lacks the member-read scope (im:chat.members:read) or the group has more than 2,000 members (no complete list), the card is posted in the group as before. Toggle it in the Dashboard (Bot Config → Authorization & Quota), via bots.json, or with /botconfig set grantRequestToOwnerDm on.

#Common questions

• On-call vs bare /grant? Both grant talk only, never operate. On-call is always allowed with no quota and also binds the group to a working directory (new topics skip repo picking); /grant only opens talk and binds no directory.
• How do I give someone exactly 3 messages? @bot /grant @someone produces the card with 3 messages / 1 hour as the defaults; pass a number after the mention or change it on the card.
• Does every new member need owner approval? No — whole-group open (bare /grant) or on-call means anyone in the group can ask immediately; per-person grants and request cards exist for when you want to keep the gate.

For more Q&A see the FAQ / Troubleshooting; for when @-mentioning is required, see @ Policy.