Choose your permissions
Permissions define exactly what your code can do inside a community, and they’re granted by the community at install time. This page helps you pick the smallest set you need, understand the difference between community and channel scopes, and declare those permissions in your manifest. You’ll also see how Root enforces permissions at runtime.
By the end of this article, you’ll be able to:
- Determine whether your code needs to request permissions.
- Identify the permissions you'll need.
What are permissions?
Root permissions determine the access you have to community resources, such as reading/writing messages, managing members, or manipulating community files.
For example, SuggestionBox might request permission to:
- Post messages in a community channel
- Read member roles to allow role-based voting.
What permissions are available?
There are two categories of permissions: community and channel.
| Scope | What it authorizes | Examples |
|---|---|---|
| Community | Access to community-level entities and settings. | Manage roles, create invites, issue bans. |
| Channel | Actions on a specific channel or its contents. | Create messages, manage channel files, kick users from voice channels. |
How to choose permissions
Follow the principle of least privilege. Start small and add only what your features demand.
-
List your features: write down what your code needs to do, in plain English. Example: “Post updates in #announcements,” “Pin a weekly summary,” “Kick trolls from voice.”
-
Map features to actions: Translate each feature into concrete actions. Example: “Post updates” → create message. “Pin a weekly summary” → manage pinned messages.
-
Map actions to permissions: Use the community permissions and channel permissions reference tables to find the exact permission you need. Prefer granular keys over
*FullControlunless you truly need everything in that scope. -
Declare: Use your Root Manifest to declare the permissions you need.
-
Test and tighten: Test with the minimal set. If you hit a permission error at runtime, add the specific missing key and re-test.
Installation grants your permissions
Community administrators will be shown the permission list before installation. By allowing the installation, the community administrators grant those permissions to your code.
How are permissions enforced?
There are permission checks in the Community API. You'll get a RootApiException if you make an API call for which you're not authorized. You can examine the errorCode inside the exception to determine whether the failure was due to a missing permission.