Skip to main content

Groups

Groups (also known as roles) are collections of permissions that can be assigned to users. They provide a convenient way to manage role-based access control (RBAC) by grouping related permissions together.

Overview​

Groups enable efficient permission management by:

  • Grouping related permissions together
  • Assigning multiple permissions to users at once
  • Implementing role-based access control patterns
  • Simplifying permission audits and updates

Key features:

  • Create custom groups with specific permissions
  • Assign users to multiple groups
  • Manage permissions at the group level
  • Support for both platform-level and organization-level groups

Key Features​

Role-Based Access Control​

Groups enable RBAC patterns:

  • Define roles like "Developers", "Managers", "Viewers"
  • Assign permissions to roles
  • Add users to roles instead of managing individual permissions
  • Change role permissions to update access for all members

Permission Bundling​

Groups bundle related permissions:

  • Read permissions (view_*)
  • Write permissions (add_, change_)
  • Delete permissions (delete_*)
  • Custom permissions (manage_, admin_)

Organization Integration​

Groups work seamlessly with organizations:

  • Organization members can be assigned to groups
  • Groups can have organization-specific permissions
  • Supports multi-organization user access

Using Groups​

Creating a Group​

Create a new 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": "Developers",
    "permission_ids": [1, 5, 9, 13]
  }'

Response:

{
  "id": 1,
  "name": "Developers",
  "user_count": 15,
  "permissions": [
    {
      "id": 1,
      "name": "Can view data",
      "codename": "view_data",
      "content_type": "data"
    },
    {
      "id": 5,
      "name": "Can add data",
      "codename": "add_data",
      "content_type": "data"
    }
  ]
}
User Count

The user_count field shows how many users are currently assigned to this group, helping you understand the impact of permission changes.

Listing Groups​

Get all groups:

curl -X GET https://your-site.taruvi.cloud/api/cloud/groups/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameters:

  • search: Search by group name
  • ordering: Sort results (e.g., name, -id, default: name)

Response:

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Developers",
      "permissions": [...]
    },
    {
      "id": 2,
      "name": "Managers",
      "permissions": [...]
    }
  ]
}

Retrieving Group Details​

Get details of a specific group:

curl -X GET https://your-site.taruvi.cloud/api/cloud/groups/{group_id}/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Updating a Group​

Update group name and permissions:

curl -X PUT https://your-site.taruvi.cloud/api/cloud/groups/{group_id}/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Developers",
    "permission_ids": [1, 5, 9, 13, 17, 21]
  }'

Partial Update​

Update only specific fields:

curl -X PATCH https://your-site.taruvi.cloud/api/cloud/groups/{group_id}/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead Developers"
  }'

Deleting a Group​

Delete a group:

curl -X DELETE https://your-site.taruvi.cloud/api/cloud/groups/{group_id}/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Note: Deleting a group:

  • Removes all user assignments to the group
  • Does not delete the users themselves
  • Removes all permissions granted through the group

Assigning Users to Groups​

Platform-Level Groups​

Users can be assigned to platform-level groups through the user management API:

curl -X GET https://your-site.taruvi.cloud/api/cloud/users/john-doe/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response includes groups:

{
  "uuid": "950e8400-e29b-41d4-a716-446655440000",
  "slug": "john-doe",
  "username": "john.doe",
  "groups": [
    {
      "id": 1,
      "name": "Developers"
    }
  ]
}

Organization-Level Groups​

Within organizations, users are assigned to groups through the OrganizationUserGroup model:

curl -X POST https://your-site.taruvi.cloud/api/cloud/organizations/acme-corp/members/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_slug": "john-doe",
    "group_ids": [1, 2]
  }'

Permission Management​

Finding Available Permissions​

List all available permissions:

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

Response:

{
  "count": 150,
  "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"
      }
    }
  ]
}

Permission Structure​

Permissions follow Django's standard format:

  • codename: Short identifier (e.g., view_organization)
  • name: Human-readable description (e.g., "Can view organization")
  • content_type: The model this permission applies to

Common Permission Patterns​

CRUD Permissions:

  • add_<model>: Create new instances
  • view_<model>: View existing instances
  • change_<model>: Update existing instances
  • delete_<model>: Delete instances

Custom Permissions:

  • manage_<model>: Full management access
  • admin_<model>: Administrative access
  • access_<model>: Basic access rights

Common Group Patterns​

Read-Only Viewer​

{
  "name": "Viewers",
  "permission_ids": [
    2,   // view_organization
    10,  // view_site
    18,  // view_user
    26   // view_data
  ]
}

Content Manager​

{
  "name": "Content Managers",
  "permission_ids": [
    26,  // view_data
    27,  // add_data
    28,  // change_data
    50,  // view_app
    51,  // add_app
    52   // change_app
  ]
}

Organization Administrator​

{
  "name": "Organization Admins",
  "permission_ids": [
    1,   // add_organization
    2,   // view_organization
    3,   // change_organization
    5,   // manage_organization
    6,   // invite_members
    10,  // view_site
    11,  // change_site
    12   // manage_site
  ]
}

Developer​

{
  "name": "Developers",
  "permission_ids": [
    2,   // view_organization
    10,  // view_site
    11,  // change_site
    26,  // view_data
    27,  // add_data
    28,  // change_data
    50,  // view_app
    51,  // add_app
    52,  // change_app
    53   // delete_app
  ]
}

System Administrator​

{
  "name": "System Admins",
  "permission_ids": [
    // All permissions - full system access
  ]
}

Best Practices​

  1. Principle of Least Privilege: Grant only necessary permissions
  2. Role Naming: Use clear, descriptive group names that indicate purpose
  3. Permission Audits: Regularly review and update group permissions
  4. Avoid User-Specific Groups: Create role-based groups, not user-specific ones
  5. Documentation: Document what each group can do
  6. Hierarchical Roles: Consider creating tiered access levels
  7. Test Permissions: Verify group permissions work as expected

Use Cases​

Multi-Tier Access​

Viewer Group
├── Permissions: view_*
└── Users: All team members

Editor Group
├── Permissions: view_*, add_*, change_*
└── Users: Content creators

Admin Group
├── Permissions: view_*, add_*, change_*, delete_*, manage_*
└── Users: Team leads

Department-Based Access​

Engineering Group
├── Permissions: Full access to sites, data, apps
└── Users: Developers, DevOps

Marketing Group
├── Permissions: View and edit content, view analytics
└── Users: Marketing team

Finance Group
├── Permissions: View billing, view reports
└── Users: Finance team

Project-Based Access​

Project A Team
├── Permissions: Access to Project A sites and data
└── Users: Project A members

Project B Team
├── Permissions: Access to Project B sites and data
└── Users: Project B members

Cross-Project Managers
├── Permissions: View all projects, manage resources
└── Users: Project managers

Permissions​

Managing groups requires:

  • view_group: View group details
  • add_group: Create new groups
  • change_group: Update group permissions
  • delete_group: Delete groups