Roles & Permissions

Hierarchical role-based access control with granular permissions for the FundlyHub platform.

Authentication

All admin endpoints require an authenticated session. Super admins bypass all permission checks.

curl -b cookies.txt -c cookies.txt \
  https://api.fundlyhub.org/api/v1/admin/roles

Role Hierarchy

Role	Level	Capabilities
super_admin	100	Full platform access, bypasses all checks
admin	80	User management, campaign moderation
moderator	60	Content review, reports
org_admin	40	Manage organization members
user	10	Standard user actions

Roles with a higher hierarchy_level automatically inherit permissions of lower-level roles.

Endpoints

Role Management

Method	Endpoint	Description
GET	/admin/roles	List all roles
POST	/admin/roles	Create a new role
PUT	/admin/roles/:id	Update role details
DELETE	/admin/roles/:id	Delete role (non-system only)

Permission Management

Method	Endpoint	Description
GET	/admin/roles/:id/permissions	List role permissions
POST	/admin/roles/:id/permissions	Add permission to role
DELETE	/admin/roles/:id/permissions/:permId	Remove permission

User Role Assignment

Method	Endpoint	Description
POST	/admin/users/:id/roles	Assign role to user
DELETE	/admin/users/:id/roles/:roleId	Revoke role from user

Error Responses

Code	Meaning
400	Validation error — missing or invalid fields
403	Forbidden — insufficient permissions
404	Role or user not found
409	Conflict — role name already exists

Best Practices

• Always validate permissions on both frontend and backend
• Use hierarchy_level for "at least" role checks
• Don't delete system roles (is_system_role = true)
• Use context-specific roles for organizations and fundraisers
• Super admins bypass all checks — assign sparingly