Permissions

Permissions control what actions users can perform in Taruvi Cloud. They provide fine-grained access control at the model and object level, supporting both Django's built-in permission system and Guardian's object-level permissions.

Overview

Taruvi Cloud uses a multi-layered permission system:

Model-level Permissions: Control access to model types (e.g., can add/view/change/delete organizations)
Object-level Permissions: Control access to specific instances (e.g., can manage Organization A but not Organization B)
Group-based Permissions: Assign permissions through groups for role-based access control
Guardian Integration: Object-level permissions for organizations, sites, and resources

Key Features

Two-Layer Permission System

Model-Level Permissions:

# User can create ANY organization
user.has_perm('core.add_organization')

# User can view ANY site
user.has_perm('core.view_site')

Object-Level Permissions:

# User can manage SPECIFIC organization
user.has_perm('core.manage_organization', organization_obj)

# User can access SPECIFIC site
user.has_perm('core.access_site', site_obj)

Permission Types

Permissions follow Django's standard CRUD pattern plus custom permissions:

add_<model>: Create new instances
view_<model>: View instances
change_<model>: Update instances
delete_<model>: Delete instances
<custom>_<model>: Custom actions (e.g., manage_organization, invite_members)

Using Permissions

Listing All Permissions

Get all available permissions in the system:

GET /api/cloud/permissions/
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "count": 150,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Can add organization",
      "codename": "add_organization",
      "content_type": {
        "id": 10,
        "app_label": "core",
        "model": "organization"
      }
    },
    {
      "id": 2,
      "name": "Can view organization",
      "codename": "view_organization",
      "content_type": {
        "id": 10,
        "app_label": "core",
        "model": "organization"
      }
    }
  ]
}

Filtering Permissions by Model

Filter permissions for specific models:

# Get all organization permissions
GET /api/cloud/permissions/?model=organization
Authorization: Bearer YOUR_ACCESS_TOKEN

# Get all site permissions
GET /api/cloud/permissions/?model=site
Authorization: Bearer YOUR_ACCESS_TOKEN

# Get all user permissions (includes User and OrganizationMember)
GET /api/cloud/permissions/?model=user
Authorization: Bearer YOUR_ACCESS_TOKEN

Valid Model Values:

site - Site model permissions
organization - Organization model permissions
user - User and OrganizationMember permissions

note

Providing an invalid model value returns a 400 error with valid options.

Searching Permissions

Search permissions by name or codename:

GET /api/cloud/permissions/?search=organization
Authorization: Bearer YOUR_ACCESS_TOKEN

Getting Permission Details

Retrieve details of a specific permission:

GET /api/cloud/permissions/{permission_id}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Permission Structure

Permission Object

{
  "id": 1,
  "name": "Can add organization",
  "codename": "add_organization",
  "content_type": {
    "id": 10,
    "app_label": "core",
    "model": "organization"
  }
}

Fields:

id: Unique identifier for the permission
name: Human-readable description
codename: Short identifier used in code (format: action_model)
content_type: The Django model this permission applies to

Permission Codename Format

Permissions follow a consistent naming pattern:

<action>_<model>

Examples:
- view_organization
- add_site
- change_user
- delete_domain
- manage_organization (custom)
- invite_members (custom)

Core Model Permissions

Organization Permissions

Permission	Codename	Description
View	`view_organization`	View organization details
Add	`add_organization`	Create new organizations
Change	`change_organization`	Update organization
Delete	`delete_organization`	Delete organization
Manage	`manage_organization`	Full management (custom)
Invite Members	`invite_members`	Send invitations (custom)
Manage Sites	`manage_sites`	Manage org sites (custom)

Site Permissions

Permission	Codename	Description
View	`view_site`	View site details
Add	`add_site`	Create new sites
Change	`change_site`	Update site settings
Delete	`delete_site`	Delete site
Access	`access_site`	Access site environment (custom)
Manage	`manage_site`	Full site management (custom)
Manage Users	`manage_site_users`	Manage site users (custom)
Admin	`admin_site`	Site administrator (custom)

User Permissions

Permission	Codename	Description
View	`view_user`	View user details
Add	`add_user`	Create new users
Change	`change_user`	Update user information
Delete	`delete_user`	Delete users

Domain Permissions

Permission	Codename	Description
View	`view_domain`	View domain configuration
Add	`add_domain`	Add new domains
Change	`change_domain`	Update domain settings
Delete	`delete_domain`	Remove domains

Group Permissions

Permission	Codename	Description
View	`view_group`	View group details
Add	`add_group`	Create new groups
Change	`change_group`	Update group permissions
Delete	`delete_group`	Delete groups

Object-Level Permissions (Guardian)

Assigning Object Permissions

Object permissions are automatically assigned when:

Creating an organization (owner gets all permissions)
Adding members to organizations (configurable permissions)
Creating sites within organizations (inherited from org)
Inviting users (invitation-specific permissions)

Checking Object Permissions

The API automatically checks object-level permissions:

# This checks if user has view_organization permission on THIS specific organization
GET /api/cloud/organizations/{org_uuid}/
Authorization: Bearer YOUR_ACCESS_TOKEN

# Returns 403 Forbidden if user lacks permission on this specific organization

Permission Inheritance

Permissions can be inherited:

Organization members inherit permissions to organization's sites
Site permissions can be granted independently
Group permissions apply to all group members

Granting Permissions

Through Groups

The recommended way to grant permissions is through groups:

# Create a group with permissions
POST /api/cloud/groups/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "Site Managers",
  "permission_ids": [10, 11, 12, 13]  // site permissions
}

# Assign user to group (handles group assignment separately)

Direct Assignment

Permissions can also be assigned directly to users, though this is not exposed through the standard API and should be done programmatically when needed.

Permission Checking in API

Authentication Required

All endpoints require authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN

Without authentication, you'll receive:

{
  "detail": "Authentication credentials were not provided."
}

Permission Denied

When lacking required permissions:

{
  "detail": "You do not have permission to perform this action."
}

Common Permission Scenarios

Scenario 1: List Organizations

GET /api/cloud/organizations/

Returns only organizations user has view_organization permission for
Empty list if no access

Scenario 2: Create Organization

POST /api/cloud/organizations/

Requires add_organization model permission
User automatically gets full permissions on created organization

Scenario 3: Update Specific Organization

PUT /api/cloud/organizations/{uuid}/

Requires change_organization permission on THAT specific organization
403 Forbidden if lacks object-level permission

Scenario 4: Delete Site

DELETE /api/sites/{uuid}/

Requires delete_site permission on THAT specific site
Also checks parent organization permissions

Best Practices

Use Groups: Assign permissions through groups, not directly to users
Least Privilege: Grant only necessary permissions
Object-Level: Use object permissions for multi-tenant isolation
Regular Audits: Review and update permissions regularly
Custom Permissions: Create custom permissions for specific business logic
Permission Naming: Follow consistent naming patterns
Documentation: Document what each permission allows

Permission Hierarchies

Organization Hierarchy

Organization Owner
├── Full organization permissions
├── All site permissions
└── Can manage all members

Organization Admin
├── View and change organization
├── Manage members
├── Manage sites
└── Cannot delete organization

Organization Member
├── View organization
└── Access assigned sites only

Site Hierarchy

Site Admin
├── Full site management
├── Manage site users
├── Change site settings
└── Manage domains

Site Manager
├── View site
├── Change site settings
├── View site users
└── Cannot delete site

Site Viewer
└── View site details only

Common Permission Sets

Read-Only Access

{
  "permissions": [
    "view_organization",
    "view_site",
    "view_user",
    "view_domain"
  ]
}

Content Manager

{
  "permissions": [
    "view_organization",
    "view_site",
    "change_site",
    "view_user",
    "add_domain",
    "change_domain"
  ]
}

Organization Administrator

{
  "permissions": [
    "view_organization",
    "change_organization",
    "manage_organization",
    "invite_members",
    "add_site",
    "view_site",
    "change_site",
    "delete_site",
    "manage_site"
  ]
}

Platform Administrator

{
  "permissions": [
    "add_organization",
    "view_organization",
    "change_organization",
    "delete_organization",
    "manage_organization",
    "add_site",
    "view_site",
    "change_site",
    "delete_site",
    "add_user",
    "view_user",
    "change_user",
    "delete_user"
  ]
}

Security Considerations

Multi-Tenancy

Object-level permissions ensure:

Users only see their organizations
Site data is completely isolated
Cross-tenant access is prevented

Permission Escalation

Prevent permission escalation by:

Validating permission grants
Checking parent object permissions
Using Guardian's object permissions
Regular permission audits

API Security

All API endpoints:

Require authentication
Check model-level permissions
Verify object-level permissions where applicable
Return appropriate error codes

Troubleshooting

"Permission Denied" Errors

If you receive permission denied errors:

Check Authentication: Ensure you're logged in
Verify Model Permission: Check if you have the base model permission
Check Object Permission: Verify you have permission on that specific object
Review Group Membership: Confirm you're in the right groups
Contact Admin: Request necessary permissions

Permission Not Available

If a permission doesn't appear in the list:

Run migrations: Permissions are created during migrations
Check custom permissions in model Meta classes
Verify ContentType exists for the model
Review permission creation in migration files

Users - User accounts with permissions
Groups - Group-based permission management
Organizations - Organization-level permissions
Sites - Site-level permissions

Overview​

Key Features​

Two-Layer Permission System​

Permission Types​

Using Permissions​

Listing All Permissions​

Filtering Permissions by Model​

Searching Permissions​

Getting Permission Details​

Permission Structure​

Permission Object​

Permission Codename Format​

Core Model Permissions​

Organization Permissions​

Site Permissions​

User Permissions​

Domain Permissions​

Group Permissions​

Object-Level Permissions (Guardian)​

Assigning Object Permissions​

Checking Object Permissions​

Permission Inheritance​

Granting Permissions​

Through Groups​

Direct Assignment​

Permission Checking in API​

Authentication Required​

Permission Denied​

Common Permission Scenarios​

Best Practices​

Permission Hierarchies​

Organization Hierarchy​

Site Hierarchy​

Common Permission Sets​

Read-Only Access​

Content Manager​

Organization Administrator​

Platform Administrator​

Security Considerations​

Multi-Tenancy​

Permission Escalation​

API Security​

Troubleshooting​

"Permission Denied" Errors​

Permission Not Available​

Related Features​