> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Roles, Permissions & Governance

> Implement role-based access control with custom roles, hierarchical permissions, and community-level governance rules.

> [!NOTE]
>
> **SDK v7.x** · Last verified March 2026 · iOS · Android · Web · Flutter

> [accordion] Speed run — just the code
>
> ```typescript theme={null}
> // 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 ↓

> [!TIP]
>
> **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.

```mermaid theme={null}
graph TD
    A[User] --> B{Global role}
    B -->|Admin| C[Full platform access]
    B -->|Regular user| D{Community role?}
    D -->|Community Admin| E[Full community control]
    D -->|Moderator| F[Moderate content + manage members]
    D -->|Member| G[Post, comment, react]
    D -->|Not a member| H[View-only for public communities]
    E --> I[Actions: edit community, assign roles, delete posts]
    F --> J[Actions: approve posts, ban members, flag content]
    G --> K[Actions: create posts, add reactions, follow users]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,D decision
    class E,F,G,H process
    class C,I,J,K outcome
```

> [!NOTE]
>
> **Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview.md). At least one community created → [Create Community](/social-plus-sdk/social/communities-spaces/community-lifecycle/create-community.md). Admin Console access needed for global role management.
>
> **Also recommended:** Complete [Community Platform](/use-cases/social/community-platform.md) first — roles and permissions govern community behavior.

> [!NOTE]
>
> **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

```typescript theme={null}
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](/social-plus-sdk/core-concepts/user-management/roles-permissions.md)

***

## Step-by-Step Implementation

**1. 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.

```typescript theme={null}
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](/social-plus-sdk/core-concepts/user-management/roles-permissions.md)

**2. 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.

```typescript theme={null}
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](/social-plus-sdk/social/communities-spaces/organization/member-management.md)

**3. 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](/social-plus-sdk/social/communities-spaces/community-lifecycle/create-community.md)

**4. Ban and unban community members**

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

```typescript theme={null}
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](/social-plus-sdk/social/communities-spaces/governance/community-moderation)

**5. 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.

```typescript theme={null}
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](/social-plus-sdk/social/content-management/posts/moderation/post-review.md)

**6. 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](/analytics-and-moderation/console/moderation/roles-and-privileges.md)

***

## 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

> [accordion] 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](/analytics-and-moderation/console/moderation/roles-and-privileges.md)

> [accordion] 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.

> [accordion] 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](/analytics-and-moderation/social+-apis-and-services/webhook-event.md)

***

## Common Mistakes

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **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

> [accordion] 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)

> [accordion] 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

> [accordion] 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")

***

> [!TIP]
>
> **Dive deeper**: [User Management API Reference](/social-plus-sdk/core-concepts/user-management/overview.md) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

> [card] [Your next step → Content Moderation Pipeline](/use-cases/social/content-moderation-pipeline.md)
>
> Roles are set — now wire up the moderation pipeline with flagging, AI review, and webhooks.

Or explore related guides:

> [card] [Community Platform](/use-cases/social/community-platform.md)
>
> Build communities that use these governance rules

> [card] [Content Moderation Pipeline](/use-cases/social/content-moderation-pipeline.md)
>
> Set up the full moderation workflow

> [card] [User Profiles & Social Graph](/use-cases/social/user-profiles-and-social-graph.md)
>
> Manage user relationships and blocking


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.