# Permissions & RBAC {#permissions--rbac}



## Permission Model {#permission-model}


MQUAD uses a **Role-Based Access Control (RBAC)** system where permissions are granular strings in the format `{resource}:{action}`.


## Permission Format {#permission-format}


```
{resource}:{action}

# Examples
survey:read      survey:write      survey:delete
user:read        user:write        user:delete
tenant:read      tenant:write      tenant:manage
response:read    response:write    response:approve
workspace:read   workspace:write   workspace:manage
```


## Admin Permissions {#admin-permissions}


Two special permissions grant elevated access:

```python
SUPER_ADMIN_PERMISSION = "super:admin"     # Full system access
FULL_ACCESS_PERMISSION = "full:access"     # Full access within tenant
HOST_MANAGE_TENANTS = "host:manage_tenants" # Tenant administration
```

**Key rule:** Admin status is determined by the **permissions list**, not a boolean field in the JWT:

```python
from common.rbac_helpers import is_super_admin, is_host_admin

# Check super admin
if is_super_admin(user_permissions):
    # Has "super:admin" or "full:access"

# Check host admin
if is_host_admin(user_permissions):
    # Has "host:manage_tenants"
```


## Permission Check Helpers {#permission-check-helpers}


`common/rbac_helpers.py` provides:

| Function | Purpose |
|----------|---------|
| `is_super_admin(permissions)` | Check for super admin or full access |
| `is_host_admin(permissions)` | Check for host manage tenants |
| `has_permission(permissions, required)` | Check a specific permission |
| `has_any_permission(permissions, required_list)` | Check any of the required |
| `has_all_permissions(permissions, required_list)` | Check all required |

```python
if has_permission(user.permissions, "survey:write"):
    # Allow editing survey

if has_any_permission(user.permissions, ["survey:write", "survey:admin"]):
    # Allow if either permission
```


## Role Hierarchy {#role-hierarchy}


```
Super Admin (cross-tenant)
  └── Host Admin (tenant management)
       └── Tenant Admin (tenant-wide)
            ├── Editor (read/write within tenant)
            │    └── Approver (can approve responses)
            └── Viewer (read-only)
```


## Permission Matrix {#permission-matrix}


| Resource | Viewer | Editor | Approver | Tenant Admin | Host Admin | Super Admin |
|----------|--------|--------|----------|--------------|------------|-------------|
| survey:read | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| survey:write | — | ✓ | — | ✓ | — | ✓ |
| survey:delete | — | — | — | ✓ | — | ✓ |
| survey:publish | — | — | — | ✓ | — | ✓ |
| response:read | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| response:write | — | ✓ | ✓ | ✓ | — | ✓ |
| response:approve | — | — | ✓ | ✓ | — | ✓ |
| user:read | — | — | — | ✓ | ✓ | ✓ |
| user:write | — | — | — | ✓ | ✓ | ✓ |
| tenant:manage | — | — | — | — | ✓ | ✓ |