Role-Based Access Control

Field	Value
Document ID	ASCEND-SEC-013
Version	1.0.0
Last Updated	December 19, 2025
Author	Ascend Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 8 minutes | Skill Level: Intermediate

Overview

ASCEND implements hierarchical role-based access control (RBAC) with granular permissions. Roles determine access levels, approval authority, and feature availability.

Role Hierarchy

+---------------------------------------------------------------------------------+
|                          ROLE HIERARCHY                                          |
+---------------------------------------------------------------------------------+
|                                                                                  |
|   Level 5: SUPER_ADMIN                                                          |
|   +-------------------------------------------------------------------------+   |
|   | - Full platform access                                                   |   |
|   | - Organization management                                                |   |
|   | - User provisioning                                                      |   |
|   | - System configuration                                                   |   |
|   +-------------------------------------------------------------------------+   |
|        |                                                                        |
|        v                                                                        |
|   Level 4: ADMIN                                                                |
|   +-------------------------------------------------------------------------+   |
|   | - Agent management                                                       |   |
|   | - Policy configuration                                                   |   |
|   | - User management (within org)                                          |   |
|   | - Approve critical actions                                              |   |
|   +-------------------------------------------------------------------------+   |
|        |                                                                        |
|        v                                                                        |
|   Level 3: MANAGER                                                              |
|   +-------------------------------------------------------------------------+   |
|   | - Team oversight                                                         |   |
|   | - Approve high-risk actions                                             |   |
|   | - View audit logs                                                        |   |
|   | - Configure smart rules                                                  |   |
|   +-------------------------------------------------------------------------+   |
|        |                                                                        |
|        v                                                                        |
|   Level 2: ANALYST                                                              |
|   +-------------------------------------------------------------------------+   |
|   | - View analytics                                                         |   |
|   | - Approve medium-risk actions                                           |   |
|   | - Create reports                                                         |   |
|   +-------------------------------------------------------------------------+   |
|        |                                                                        |
|        v                                                                        |
|   Level 1: VIEWER                                                               |
|   +-------------------------------------------------------------------------+   |
|   | - Read-only access                                                       |   |
|   | - View dashboards                                                        |   |
|   | - View action history                                                    |   |
|   +-------------------------------------------------------------------------+   |
|                                                                                  |
+---------------------------------------------------------------------------------+

Role Definitions

Role	Level	Approval Authority	Key Permissions
`super_admin`	5	All actions	Full platform access
`admin`	4	Critical (80+)	Agent/policy management
`manager`	3	High (60-80)	Team oversight, rules
`analyst`	2	Medium (30-60)	Analytics, reports
`viewer`	1	None	Read-only access

Permission Categories

Agent Permissions

Permission	Description	Roles
`agent:read`	View agents	All
`agent:write`	Create/update agents	admin, super_admin
`agent:delete`	Delete agents	super_admin
`agent:approve`	Approve agent registration	admin, super_admin

Action Permissions

Permission	Description	Roles
`action:read`	View actions	All
`action:submit`	Submit actions	analyst+, SDK
`action:approve`	Approve pending actions	Based on risk level
`action:deny`	Deny pending actions	manager+

Policy Permissions

Permission	Description	Roles
`policy:read`	View policies	All
`policy:write`	Create/update policies	admin, super_admin
`policy:delete`	Delete policies	super_admin
`policy:activate`	Activate policies	admin, super_admin

Analytics Permissions

Permission	Description	Roles
`analytics:read`	View analytics	analyst+
`analytics:export`	Export data	manager+
`analytics:executive`	Executive dashboard	admin+

Audit Permissions

Permission	Description	Roles
`audit:read`	View audit logs	analyst+
`audit:export`	Export audit logs	admin+
`audit:compliance`	Compliance reports	admin+

Approval Authority Matrix

Risk-Based Approval

Risk Level	Score Range	Required Role
Low	0-30	Auto-approve (no role needed)
Medium	30-60	analyst (level 2+)
High	60-80	manager (level 3+)
Critical	80-100	admin (level 4+)

Multi-Approval Requirements

# High-value actions may require multiple approvers
{
    "conditions": {"amount_above": 100000},
    "action_params": {
        "approvers_required": 3,
        "approver_roles": ["manager", "admin", "super_admin"]
    }
}

API Key Permissions

Scoped API Keys

curl -X POST "https://pilot.owkai.app/api/keys/generate" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "name": "Read-Only Analytics Key",
    "permissions": [
      {"category": "action", "actions": ["read"]},
      {"category": "analytics", "actions": ["read"]}
    ]
  }'

Permission Validation

# API key permissions are checked on each request
def check_permission(api_key, required_permission):
    for perm in api_key.permissions:
        if perm.category == required_permission.category:
            if required_permission.action in perm.actions:
                return True
    return False

SSO Group Mapping

Group-to-Role Mapping

# Source: sso_manager.py:64
GROUP_TO_ROLE_MAPPING = {
    # Okta Groups
    "OW-AI-Executives": 5,        # super_admin
    "OW-AI-Administrators": 4,    # admin
    "OW-AI-Managers": 3,          # manager
    "OW-AI-Analysts": 2,          # analyst
    "OW-AI-Users": 1,             # viewer

    # Azure AD Groups
    "OW-AI Executive Team": 5,
    "OW-AI System Administrators": 4,
    "OW-AI Security Managers": 3
}

Automatic Role Assignment

def assign_role_from_groups(groups: List[str]) -> str:
    """Assign highest matching role from IdP groups."""
    max_level = 0
    for group in groups:
        if group in GROUP_TO_ROLE_MAPPING:
            level = GROUP_TO_ROLE_MAPPING[group]
            max_level = max(max_level, level)

    return LEVEL_TO_ROLE[max_level]

User Management

Create User with Role

curl -X POST "https://pilot.owkai.app/api/admin/users" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "email": "analyst@company.com",
    "role": "analyst",
    "organization_id": 1
  }'

Update User Role

curl -X PUT "https://pilot.owkai.app/api/admin/users/123" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{
    "role": "manager"
  }'

Route Protection

Role-Based Route Guards

from dependencies import require_role

@router.post("/policies")
async def create_policy(
    current_user: dict = Depends(require_role(["admin", "super_admin"]))
):
    """Only admins can create policies."""
    pass

@router.get("/analytics/executive")
async def executive_dashboard(
    current_user: dict = Depends(require_role(["admin", "super_admin"]))
):
    """Executive dashboard requires admin access."""
    pass

Minimum Role Check

def require_minimum_role(minimum_level: int):
    """Require user to have at least specified role level."""
    def check(current_user: dict):
        user_level = ROLE_LEVELS.get(current_user.get("role"), 0)
        if user_level < minimum_level:
            raise HTTPException(
                status_code=403,
                detail="Insufficient permissions"
            )
        return current_user
    return check

Compliance Mapping

Standard	Requirement	Implementation
SOC 2 CC6.1	Logical access controls	RBAC policies
SOC 2 CC6.3	Role-based access	Hierarchical roles
PCI-DSS 7.1	Need-to-know access	Permission scoping
NIST AC-2	Account management	User provisioning
NIST AC-3	Access enforcement	Route guards

Best Practices

1. Principle of Least Privilege

# Assign minimum necessary role
{
    "role": "analyst",  # Not admin if analytics is all they need
    "permissions": ["analytics:read"]
}

2. Regular Access Reviews

# Review and audit role assignments
for user in organization.users:
    if user.last_active < ninety_days_ago:
        flag_for_review(user)

3. Use API Key Scoping

# Limit API keys to necessary permissions
{
    "permissions": ["action:submit", "action:read"]
    # Don't include agent:delete for action-submission keys
}

4. Audit Role Changes

# Log all role modifications
{
    "event_type": "ROLE_CHANGE",
    "user_id": 123,
    "old_role": "analyst",
    "new_role": "manager",
    "changed_by": "admin@company.com"
}

Next Steps

Multi-Tenancy — Organization isolation
Data Protection — Encryption
Audit Compliance — Compliance logging

Document Version: 1.0.0 | Last Updated: December 2025

Overview​

Role Hierarchy​

Role Definitions​

Permission Categories​

Agent Permissions​

Action Permissions​

Policy Permissions​

Analytics Permissions​

Audit Permissions​

Approval Authority Matrix​

Risk-Based Approval​

Multi-Approval Requirements​

API Key Permissions​

Scoped API Keys​

Permission Validation​

SSO Group Mapping​

Group-to-Role Mapping​

Automatic Role Assignment​

User Management​

Create User with Role​

Update User Role​

Route Protection​

Role-Based Route Guards​

Minimum Role Check​

Compliance Mapping​

Best Practices​

1. Principle of Least Privilege​

2. Regular Access Reviews​

3. Use API Key Scoping​

4. Audit Role Changes​

Next Steps​