Org & Project Permissions

Overview

Akhara uses a hierarchical permission model where access is controlled at two levels:

Organization Level: Global settings, billing, user management, and cross-project visibility
Project Level: Datasets, evaluations, reviews, and project-specific configurations

Permissions cascade down: organization admins have access to all projects, while project-level roles are scoped to specific projects.

Permission Hierarchy

Organization
├── Org Owner (full control)
├── Org Admin (manage users, settings)
├── Org Member (access assigned projects only)
│
└── Projects
    ├── Project Admin (full project control)
    ├── Developer (build & run evaluations)
    ├── Reviewer (grade AI outputs)
    └── Viewer (read-only access)

Organization Permissions

Organization Settings

Setting	Owner	Admin	Member
View org dashboard	✓	✓	✓
Manage billing & subscription	✓	✓	-
Configure SSO/SAML	✓	✓	-
Manage API keys (org-level)	✓	✓	-
View all projects	✓	✓	-
Create new projects	✓	✓	✓*
Delete projects	✓	✓	-
Manage org members	✓	✓	-
Transfer ownership	✓	-	-
Delete organization	✓	-	-

*Members can create projects if enabled in org settings

User Management

Action	Owner	Admin	Member
Invite users to org	✓	✓	-
Remove users from org	✓	✓	-
Change user org roles	✓	✓	-
View user activity	✓	✓	-
Manage reviewer credentials	✓	✓	-

Project Permissions

Project Configuration

Action	Project Admin	Developer	Reviewer	Viewer
View project dashboard	✓	✓	✓	✓
Edit project settings	✓	-	-	-
Configure evaluators	✓	✓	-	-
Manage webhooks	✓	✓	-	-
Create API keys (project)	✓	✓	-	-
Add/remove project members	✓	-	-	-
Delete project	✓	-	-	-

Data & Evaluation Access

Action	Project Admin	Developer	Reviewer	Viewer
Create datasets	✓	✓	-	-
Upload samples	✓	✓	-	-
View samples	✓	✓	✓	✓
Access PHI fields	✓*	-	✓*	-
Run evaluations	✓	✓	-	-
View evaluation results	✓	✓	✓	✓
Export data	✓	✓	-	✓

*Requires explicit PHI access grant

Review Queue Access

Action	Project Admin	Developer	Reviewer	Viewer
View review queue	✓	-	✓	-
Claim review tasks	✓	-	✓	-
Submit reviews	✓	-	✓	-
Override AI scores	✓	-	✓*	-
Assign tasks to reviewers	✓	-	-	-
View all review history	✓	✓	✓	✓

*Within credentialed scope only

Managing Access

Invite Users to Organization

from akhara import Akhara

client = Akhara()

# Invite with org role
invitation = client.org.invite(
    email="[email protected]",
    role="member",
    message="Welcome to our Akhara organization!"
)

print(f"Invitation sent: {invitation.id}")

Add Users to Projects

# Add member to specific project with role
client.projects.add_member(
    project="proj_triage_v2",
    user="user_abc123",
    role="developer"
)

# Add clinical reviewer (requires credential verification)
client.projects.add_member(
    project="proj_triage_v2",
    user="user_dr_smith",
    role="reviewer",
    reviewer_config={
        "type": "physician",
        "license_number": "MD12345",
        "license_state": "CA",
        "specialties": ["internal_medicine", "emergency"]
    }
)

Bulk Permission Updates

# Add multiple users to a project
client.projects.add_members(
    project="proj_triage_v2",
    members=[
        {"user": "user_a", "role": "developer"},
        {"user": "user_b", "role": "developer"},
        {"user": "user_c", "role": "viewer"}
    ]
)

# Update role for existing member
client.projects.update_member(
    project="proj_triage_v2",
    user="user_a",
    role="project_admin"
)

Project Visibility

Control which projects users can see:

Visibility Modes

Mode	Description	Use Case
Private	Only assigned members can see	Default for most projects
Org-Visible	All org members can view (read-only)	Shared dashboards, reference projects
Restricted	Hidden from org admins unless explicitly granted	Sensitive PHI, executive reviews

# Set project visibility
client.projects.update(
    project="proj_triage_v2",
    visibility="private"  # or "org_visible", "restricted"
)

PHI Access Control

PHI access is controlled separately from general permissions:

Grant PHI Access

# Grant PHI access to a user for a specific project
client.projects.grant_phi_access(
    project="proj_triage_v2",
    user="user_abc123",
    justification="Clinical reviewer requiring access to transcripts",
    expires_at="2024-12-31T23:59:59Z"  # Optional expiration
)

PHI Access Policies

Policy	Description
`explicit_grant`	PHI access requires explicit per-user grant (default)
`role_based`	Certain roles automatically get PHI access
`time_limited`	PHI access expires after set duration
`audit_required`	Each PHI access requires justification

# Configure project PHI policy
client.projects.update(
    project="proj_triage_v2",
    phi_policy={
        "access_mode": "explicit_grant",
        "require_justification": True,
        "max_duration_days": 90,
        "auto_revoke_inactive_days": 30
    }
)

Team Management

Create Teams

Organize users into teams for easier permission management:

# Create a team
team = client.teams.create(
    name="Clinical Review Team",
    description="Licensed clinicians for triage review",
    members=["user_dr_smith", "user_dr_jones", "user_np_wilson"]
)

# Add team to project
client.projects.add_team(
    project="proj_triage_v2",
    team=team.id,
    role="reviewer"
)

Team Permissions

When a team is added to a project, all team members inherit the assigned role. Individual overrides can be applied:

# Override role for specific team member
client.projects.update_member(
    project="proj_triage_v2",
    user="user_dr_smith",
    role="project_admin",  # Override team's "reviewer" role
    override_team=True
)

Access Requests

Enable self-service access requests for governed onboarding:

# Enable access requests for a project
client.projects.update(
    project="proj_triage_v2",
    access_requests={
        "enabled": True,
        "approvers": ["user_admin_1", "user_admin_2"],
        "require_justification": True,
        "auto_expire_days": 90
    }
)

Users can then request access:

# Request access to a project
client.projects.request_access(
    project="proj_triage_v2",
    role="viewer",
    justification="Need to review evaluation results for Q1 report"
)

Best Practices

Least Privilege

Start with Viewer role and escalate only as needed

Use Teams

Group users by function for easier management

Regular Reviews

Audit project membership quarterly

PHI Minimization

Only grant PHI access with documented justification

Role-Based Access Control

Detailed role definitions and permission matrix

Audit Logs

Track all permission changes and access events

​Overview

​Permission Hierarchy

​Organization Permissions

​Organization Settings

​User Management

​Project Permissions

​Project Configuration

​Data & Evaluation Access

​Review Queue Access

​Managing Access

​Invite Users to Organization

​Add Users to Projects

​Bulk Permission Updates

​Project Visibility

​Visibility Modes

​PHI Access Control

​Grant PHI Access

​PHI Access Policies

​Team Management

​Create Teams

​Team Permissions

​Access Requests

​Best Practices