Roles, Permissions & Governance

SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter

Speed run — just the code

// 1. Check if user has a specific permission
const allowed = await client.hasPermission('editCommunity')
  .community('communityId')
  .check();

// 2. Assign a community role
await ChannelRepository.Moderation.addRole(
  'communityId', ['userId'], 'moderator'
);

// 3. Remove a community role
await ChannelRepository.Moderation.removeRole(
  'communityId', ['userId'], 'moderator'
);

Full walkthrough below ↓

Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step.

As your platform grows beyond a single community, you need a permission system. social.plus provides a hierarchical RBAC model: global roles → community roles → per-action permissions. This guide covers checking permissions in the SDK, assigning community roles, and configuring governance rules.

Prerequisites: SDK installed and authenticated → SDK Setup. At least one community created → Create Community. Admin Console access needed for global role management.Also recommended: Complete Community Platform first — roles and permissions govern community behavior.

After completing this guide you’ll have:

SDK permission checks (hasPermission) gating actions in your UI
Community moderator role assignment and revocation working
Post review mode (content gating) enabled in at least one community
User ban and unban flows implemented

Quick Start: Check a Permission

try {
  const canEdit = await client.hasPermission({
    permission: 'EDIT_COMMUNITY_POST',
    communityId: 'community123',
  });

  if (canEdit) {
    showEditButton();
  }
} catch (error) {
  console.error('Permission check failed:', error);
}

Full reference → Roles & Permissions

Step-by-Step Implementation

Check permissions before showing UI

Always check permissions before rendering action buttons (edit, delete, ban, etc.). This prevents users from seeing controls they can’t use and avoids server-side permission errors.

const canEdit = await client.hasPermission({
  permission: 'EDIT_COMMUNITY_POST',
  communityId: 'community123',
});

const canBan = await client.hasPermission({
  permission: 'BAN_COMMUNITY_USER',
  communityId: 'community123',
});

Full reference → Roles & Permissions

Assign community moderator roles

Promote a member to moderator via the member management API. Moderators can approve/reject posts, ban users, and manage content within their community.

import { CommunityRepository } from '@amityco/ts-sdk';

// Add roles to a member
await ChannelRepository.Moderation.addRole(communityId, 'userId', ['moderator']);

// Remove a role
await ChannelRepository.Moderation.removeRole(communityId, 'userId', ['moderator']);

Full reference → Member Management

Configure post moderation settings

Set the postSettings when creating or updating a community to control who can post and whether posts need approval.

Setting	Who posts	Review needed	Best for
`ANYONE_CAN_POST`	All members	No	Open communities
`ADMIN_REVIEW_POST_REQUIRED`	All members	Yes, admin approves	Curated communities
`ONLY_ADMIN_CAN_POST`	Admins/mods only	No	Announcement channels

Full reference → Create Community

Ban and unban community members

Community admins and moderators can ban members who violate guidelines. Banned users cannot view or interact with the community.

import { CommunityRepository } from '@amityco/ts-sdk';

// Ban a member
await CommunityRepository.Moderation.banMembers(communityId, ['userId']);

// Unban a member
await CommunityRepository.Moderation.unbanMembers(communityId, ['userId']);

Full reference → Community Moderation

Review and approve pending posts

When a community uses ADMIN_REVIEW_POST_REQUIRED, new posts land in the reviewing feed type. Check a post’s feedType to know its state, then approve or decline it. Only users with the REVIEW_COMMUNITY_POST permission can take these actions.

import { PostRepository } from '@amityco/ts-sdk';

// Check a post's review status
const isUnderReview = post.feedType === Amity.FeedType.Reviewing;
const isPublished  = post.feedType === Amity.FeedType.Published;
const isDeclined   = post.feedType === Amity.FeedType.Declined;

// Approve — moves post to published feed
await PostRepository.approvePost(post.postId);

// Decline — moves post to declined feed (author can still see it)
await PostRepository.declinePost(post.postId);

Full reference → Post Review

Manage global roles in the Admin Console

Global roles (super admin, admin, support) are managed in Admin Console → Settings → Admin Access Control. These roles grant cross-community permissions.→ Admin Console: Roles & Privileges

Permission Reference

Permission	Description	Who has it by default
`EDIT_COMMUNITY_POST`	Edit any post in a community	Community admin, moderator
`DELETE_COMMUNITY_POST`	Delete any post in a community	Community admin, moderator
`BAN_COMMUNITY_USER`	Ban/unban members	Community admin, moderator
`EDIT_COMMUNITY`	Change community name, description, settings	Community admin
`REVIEW_COMMUNITY_POST`	Approve/decline posts in review queue	Community admin, moderator
`MUTE_COMMUNITY_USER`	Temporarily silence a member	Community admin, moderator

Connect to Moderation & Analytics

Admin Console: role management

Create custom roles with specific permission sets in Admin Console → Settings → Roles. Assign users to roles globally or per-community.→ Roles & Privileges

Moderation audit trail

All moderator actions (ban, post removal, role change) are logged. Review the audit trail in Admin Console → Moderation → Activity Log for compliance.

Webhook: role change events

Receive community.role.assigned and community.role.removed webhook events to sync role state with your backend or trigger notifications.→ Webhook Events

Common Mistakes

Checking permissions only on the client — Client-side permission checks are for UI gating only. The server enforces permissions regardless, but relying solely on client checks creates a confusing UX when the server rejects an action.

Assigning roles without verifying the assigner’s permission — Only users with editCommunityUser permission can assign roles. Check this before showing the role assignment UI to avoid failed requests.

Forgetting that global roles override community roles — A global admin can do anything in any community, even without a community-level role. Don’t build UI that implies global admins need community roles.

Best Practices

Defense in depth

Check permissions in the SDK before showing UI elements (buttons, menus)
The server enforces permissions even if the client doesn’t check — but a good UX never shows controls a user can’t use
Assign at least 2 moderators per community to avoid single-point-of-failure moderation
Use ADMIN_REVIEW_POST_REQUIRED for communities with compliance requirements (healthcare, finance, education)

Role hierarchy design

Keep your role hierarchy flat: admin → moderator → member is sufficient for most apps
Don’t create more than 3-4 custom roles — complexity creates confusion
Define clear escalation paths: moderator handles content, admin handles users, super admin handles settings
Document role responsibilities in community guidelines

User experience

Show a “You’re now a moderator” notification when someone is promoted
Surface moderation tools contextually: show “Approve” button inline on queued posts, not buried in settings
Give moderators a dedicated “Mod queue” view with pending posts and flagged content
Let users see their own role in the community header (“You are a Moderator”)

Dive deeper: User Management API Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

Next Steps

Your next step → Content Moderation Pipeline

Roles are set — now wire up the moderation pipeline with flagging, AI review, and webhooks.

Or explore related guides:

Community Platform

Build communities that use these governance rules

Content Moderation Pipeline

Set up the full moderation workflow

User Profiles & Social Graph

Manage user relationships and blocking

Overview

Build Your Community

Create & Share Content

Communication

Engage & Grow

Livestream

Monetize

Roles, Permissions & Governance

Quick Start: Check a Permission

Step-by-Step Implementation

Permission Reference

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps

Your next step → Content Moderation Pipeline

Community Platform

Content Moderation Pipeline

User Profiles & Social Graph

​Quick Start: Check a Permission

​Step-by-Step Implementation

​Permission Reference

​Connect to Moderation & Analytics

​Common Mistakes

​Best Practices

​Next Steps

Your next step → Content Moderation Pipeline

Community Platform

Content Moderation Pipeline

User Profiles & Social Graph

Quick Start: Check a Permission

Step-by-Step Implementation

Permission Reference

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps