Kaha Create: Roles and Permissions Technical Reference

Overview

Kaha Create implements a hierarchical RBAC (Role-Based Access Control) system for multi-organisation knowledge hubs. This document provides technical staff with complete role definitions, permission matrices, and troubleshooting guidance.

Role Hierarchy

Super-admin (Platform Level)
    ↓
Owner (Organisation Level)
    ↓
Admin (Organisation Level)
    ↓
Creator (Organisation Level)
    ↓
Viewer (Organisation Level)

Complete Role Definitions

Super-admin (Platform Level)

Assignment: Kaha Create technical and support staff only
Database: Platform-level flag in admin table

Full Permissions:

• Access all organisations and content across platform

• Assign admin access to any organisation

• Manage platform-wide configurations

• Access system analytics and usage data

• Create organisations on behalf of users

• Transfer organisation ownership

• Manage billing and subscription issues

• View and manage all user accounts

• Reset passwords and resolve account issues

• Assign or remove any role at any level

Restrictions:

• Cannot edit content without proper organisational permissions

• Must not make changes affecting cultural integrity without consultation

Technical Notes:

• Super-admin access bypasses standard permission checks

• All Super-admin actions should be logged for audit purposes

• Use with caution - full platform access

Owner (Organisation Level)

Assignment: Organisation creator or transferred ownership
Database: user_organisations.role = 'owner'

Full Permissions:

Organisation Management:

• Complete control over organisation settings and branding

• Manage billing and subscription plans

• Delete or transfer organisation ownership

• Set organisation-wide policies and access controls

User Management:

• Invite users with any role (Admin, Creator, Viewer)

• Remove any user from organisation

• Change user roles within organisation

• Manage invitation settings and approval processes

Content Management:

• Create unlimited Shareables (within plan limits)

• View all Shareables in organisation

• Set content visibility and access controls

• Manage content categories and organisation structure

Advanced Features:

• Access organisation analytics and insights

• Configure custom domains and branding

• Export organisation data

• Manage API access and integrations

Restrictions:

• Cannot edit Shareables created by other users (unless explicit permission granted)

• Cannot access content from other organisations (unless invited)

• Cannot make platform-wide changes outside their organisation

Technical Notes:

• Only one Owner per organisation (but can have multiple via transfer)

• Owner role cannot be self-assigned

• Transferring ownership requires confirmation from new Owner

Admin (Organisation Level)

Assignment: Invited by Owner
Database: user_organisations.role = 'admin'

Full Permissions:

User Management:

• Invite new users (Admin, Creator, Viewer roles only)

• Remove users (except Owners)

• View user activity and engagement

Content Management:

• Create Shareables within organisation

• View all Shareables in organisation

• Organise and categorise content

• Manage content approval workflows (if enabled)

Organisation Support:

• Access basic organisation settings (read-only for sensitive settings)

• View organisation analytics

• Manage content categories and tags

• Support other users with platform questions

Restrictions:

• Cannot create new organisations

• Cannot edit Shareables created by others

• Cannot access billing or subscription management

• Cannot delete organisation

• Cannot change organisation ownership

• Cannot remove or demote Owners

• Cannot assign other Admins (only Owners can)

Technical Notes:

• Multiple Admins permitted per organisation

• Admin permissions are organisation-specific

• Cannot escalate own permissions

Creator (Organisation Level)

Assignment: Invited by Owner or Admin
Database: user_permissions.creator_access = 1 OR user_organisations.role = 'creator'

Full Permissions:

Content Creation:

• Create unlimited Shareables (within organisation plan limits)

• Use all content creation tools (teleprompter, AI editing, etc.)

• Upload and edit own video, audio, and text content

• Set access controls for own content

Content Management:

• Edit and update own Shareables

• Delete own Shareables

• View engagement analytics for own content

• Collaborate on content with other Creators (if enabled)

Organisation Participation:

• View other Shareables with appropriate access

• Comment and engage with content (if enabled)

• Access organisation resources and templates

Restrictions:

• Cannot invite users to organisation

• Cannot edit content created by others

• Cannot access organisation-wide analytics

• Cannot change organisation settings

• Cannot remove other users

• Cannot access billing information

Technical Notes:

• Creator flag in user_permissions table indicates Creator access

• Creators can be members of multiple organisations with different permissions

• Content ownership tied to creator user ID

Viewer (Organisation Level)

Assignment: Invited by Owner or Admin
Database: user_organisations.role = 'viewer'

Full Permissions:

Content Access:

• View Shareables with appropriate permissions

• Engage with interactive content (quizzes, exercises)

• Download resources (if permitted by content creator)

• Track own learning progress

Basic Interaction:

• Comment on content (if enabled)

• Provide feedback and ratings

• Bookmark favourite content

• Share content externally (if permitted)

Restrictions:

• Cannot create any Shareables

• Cannot edit any content

• Cannot invite other users

• Cannot access organisation management features

• Cannot view organisation analytics

• Cannot access restricted content

Technical Notes:

• Viewer is most restrictive role

• Viewers may have access to multiple organisations

• Content visibility controlled by creator permissions

Multi-Organisation Access

Technical Implementation:

• Users can have different roles in different organisations

• user_organisations table tracks role per organisation

• User must select target organisation when creating content

• Permissions checked per-organisation for every action

Database Structure:

user_organisations
├── user_id
├── organisation_id
├── role (owner/admin/creator/viewer)
└── created_at

user_permissions
├── user_id
├── organisation_id
└── creator_access (1/0)

Example Scenarios:

User A:

• Organisation 1: Owner

• Organisation 2: Creator

• Organisation 3: Viewer

Behaviour:

• Can invite users only in Organisation 1

• Can create content in Organisations 1 and 2

• Can only view content in Organisation 3

Invitation System

Technical Flow:

1. Owner/Admin generates invitation with specified role

2. Invitation stored in invitations table with role assignment

3. Recipient accepts invitation

4. System automatically assigns specified role in user_organisations

5. Invitation marked as accepted and expired

Permission Matrix:

Inviting Role

Can Invite As

Database Schema:

invitations
├── id
├── organisation_id
├── invited_by (user_id)
├── invited_role
├── email
├── token
├── expires_at
└── accepted_at

Content Permissions

Ownership Rules:

• Creators own their content (stored in shareables.creator_id)

• Only creator can edit their Shareables (unless collaboration enabled)

• Organisation members can view based on access settings

• Content cannot cross organisations unless explicitly shared

Permission Checks:

Can Edit Content:
- User is content creator
- User is Super-admin
- User has explicit collaboration permission

Can View Content:
- User has organisation membership
- Content visibility settings permit access
- User has direct share access
- User is Super-admin

Special Cases:

• Collaborative content: Multiple creators in shareable_collaborators table

• Organisation templates: Special flag in shareables table

• Archived content: archived_at timestamp, only Owner can permanently delete

Troubleshooting Guide

Common Issues:

User can't create content:

Check:
1. user_permissions.creator_access = 1?
2. Organisation plan limits reached?
3. User role in user_organisations?
4. Correct organisation selected?

User can't see expected content:

Check:
1. User organisation membership?
2. Content visibility settings?
3. Shareable status (draft/published)?
4. User role permits viewing?

User can't invite others:

Check:
1. User role is Owner or Admin?
2. Organisation invitation settings?
3. Plan limits on user count?

Permission changes not taking effect:

Actions:
1. Check cache expiry (permissions cached 5 minutes)
2. Verify database update completed
3. Check for multiple sessions
4. Review API endpoint permission middleware

API Implementation Notes

Endpoint Permission Checks:

• All endpoints validate user permissions before action

• Multi-organisation users must include organisation_id in requests

• Role changes propagate immediately (but respect cache)

• Failed permission checks return 403 Forbidden

Standard Headers:

Authorization: Bearer {token}
X-Organisation-ID: {organisation_id}

Permission Middleware:

javascript

requireRole(['owner', 'admin']) // Endpoint level
checkContentOwnership(userId, shareableId) // Content level
verifyOrganisationMembership(userId, orgId) // Organisation level

Database Queries for Support

Check user's roles across organisations:

sql

SELECT o.name, uo.role, up.creator_access
FROM user_organisations uo
JOIN organisations o ON uo.organisation_id = o.id
LEFT JOIN user_permissions up ON up.user_id = uo.user_id 
  AND up.organisation_id = uo.organisation_id
WHERE uo.user_id = ?

Find all organisation Admins:

sql

SELECT u.email, u.name, uo.created_at
FROM user_organisations uo
JOIN users u ON uo.user_id = u.id
WHERE uo.organisation_id = ? AND uo.role = 'admin'

Check content permissions:

sql

SELECT s.title, s.creator_id, u.name as creator_name, s.visibility
FROM shareables s
JOIN users u ON s.creator_id = u.id
WHERE s.organisation_id = ?

Security Notes

• Never manually override permissions without proper authorisation

• All permission changes must be logged

• Super-admin access should be audited regularly

• Invitation tokens expire after 7 days by default

• Failed permission attempts should be monitored for suspicious activity

Support Escalation

Level 1: Basic permission questions, invitation issues
Level 2: Role assignment problems, content visibility issues
Level 3: Database permission inconsistencies, system-wide access problems
Level 4: Platform architecture issues, security concerns

For Level 3+ issues, engage senior technical staff immediately.