Skip to main content

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:

curl -X GET https://your-site.taruvi.cloud/api/cloud/permissions/ \
  -H "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
curl -X GET "https://your-site.taruvi.cloud/api/cloud/permissions/?model=organization" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get all site permissions
curl -X GET "https://your-site.taruvi.cloud/api/cloud/permissions/?model=site" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get all user permissions (includes User and OrganizationMember)
curl -X GET "https://your-site.taruvi.cloud/api/cloud/permissions/?model=user" \
  -H "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:

curl -X GET "https://your-site.taruvi.cloud/api/cloud/permissions/?search=organization" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Getting Permission Details​

Retrieve details of a specific permission:

curl -X GET https://your-site.taruvi.cloud/api/cloud/permissions/{permission_id}/ \
  -H "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​

PermissionCodenameDescription
Viewview_organizationView organization details
Addadd_organizationCreate new organizations
Changechange_organizationUpdate organization
Deletedelete_organizationDelete organization
Managemanage_organizationFull management (custom)
Invite Membersinvite_membersSend invitations (custom)
Manage Sitesmanage_sitesManage org sites (custom)

Site Permissions​

PermissionCodenameDescription
Viewview_siteView site details
Addadd_siteCreate new sites
Changechange_siteUpdate site settings
Deletedelete_siteDelete site
Accessaccess_siteAccess site environment (custom)
Managemanage_siteFull site management (custom)
Manage Usersmanage_site_usersManage site users (custom)
Adminadmin_siteSite administrator (custom)

User Permissions​

PermissionCodenameDescription
Viewview_userView user details
Addadd_userCreate new users
Changechange_userUpdate user information
Deletedelete_userDelete users

Domain Permissions​

PermissionCodenameDescription
Viewview_domainView domain configuration
Addadd_domainAdd new domains
Changechange_domainUpdate domain settings
Deletedelete_domainRemove domains

Group Permissions​

PermissionCodenameDescription
Viewview_groupView group details
Addadd_groupCreate new groups
Changechange_groupUpdate group permissions
Deletedelete_groupDelete 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
curl -X GET https://your-site.taruvi.cloud/api/cloud/organizations/{org_uuid}/ \
  -H "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
curl -X POST https://your-site.taruvi.cloud/api/cloud/groups/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Site Managers",
    "permission_ids": [10, 11, 12, 13]
  }'

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

curl -X GET https://your-site.taruvi.cloud/api/cloud/organizations/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  • Returns only organizations user has view_organization permission for
  • Empty list if no access

Scenario 2: Create Organization

curl -X POST https://your-site.taruvi.cloud/api/cloud/organizations/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Organization"}'
  • Requires add_organization model permission
  • User automatically gets full permissions on created organization

Scenario 3: Update Specific Organization

curl -X PUT https://your-site.taruvi.cloud/api/cloud/organizations/{uuid}/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Organization"}'
  • Requires change_organization permission on THAT specific organization
  • 403 Forbidden if lacks object-level permission

Scenario 4: Delete Site

curl -X DELETE https://your-site.taruvi.cloud/api/sites/{uuid}/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  • Requires delete_site permission on THAT specific site
  • Also checks parent organization permissions

Best Practices​

  1. Use Groups: Assign permissions through groups, not directly to users
  2. Least Privilege: Grant only necessary permissions
  3. Object-Level: Use object permissions for multi-tenant isolation
  4. Regular Audits: Review and update permissions regularly
  5. Custom Permissions: Create custom permissions for specific business logic
  6. Permission Naming: Follow consistent naming patterns
  7. 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:

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

Permission Not Available​

If a permission doesn't appear in the list:

  1. Run migrations: Permissions are created during migrations
  2. Check custom permissions in model Meta classes
  3. Verify ContentType exists for the model
  4. Review permission creation in migration files
  • Users - User accounts with permissions
  • Groups - Group-based permission management
  • Organizations - Organization-level permissions
  • Sites - Site-level permissions