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:

POST /api/cloud/groups/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "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:

GET /api/cloud/groups/
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:

GET /api/cloud/groups/{group_id}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Updating a Group

Update group name and permissions:

PUT /api/cloud/groups/{group_id}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "Senior Developers",
  "permission_ids": [1, 5, 9, 13, 17, 21]
}

Partial Update

Update only specific fields:

PATCH /api/cloud/groups/{group_id}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "Lead Developers"
}

Deleting a Group

Delete a group:

DELETE /api/cloud/groups/{group_id}/
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:

# Get user with groups
GET /api/cloud/users/{user_slug}/
Authorization: Bearer YOUR_ACCESS_TOKEN

# Example
GET /api/cloud/users/john-doe/

# 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:

# This is handled through organization member management
POST /api/cloud/organizations/{org_slug}/members/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "user_slug": "john-doe",
  "group_ids": [1, 2]
}

# Example
POST /api/cloud/organizations/acme-corp/members/
{
  "user_slug": "john-doe",
  "group_ids": [1, 2]
}

Permission Management

Finding Available Permissions

List all available permissions:

GET /api/cloud/permissions/
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

Principle of Least Privilege: Grant only necessary permissions
Role Naming: Use clear, descriptive group names that indicate purpose
Permission Audits: Regularly review and update group permissions
Avoid User-Specific Groups: Create role-based groups, not user-specific ones
Documentation: Document what each group can do
Hierarchical Roles: Consider creating tiered access levels
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

Users - Assign users to groups
Permissions - Manage individual permissions
Organizations - Organization-level group assignments
Sites - Site-level access control

Overview​

Key Features​

Role-Based Access Control​

Permission Bundling​

Organization Integration​

Using Groups​

Creating a Group​

Listing Groups​

Retrieving Group Details​

Updating a Group​

Partial Update​

Deleting a Group​

Assigning Users to Groups​

Platform-Level Groups​

Organization-Level Groups​

Permission Management​

Finding Available Permissions​

Permission Structure​

Common Permission Patterns​

Common Group Patterns​

Read-Only Viewer​

Content Manager​

Organization Administrator​

Developer​

System Administrator​

Best Practices​

Use Cases​

Multi-Tier Access​

Department-Based Access​

Project-Based Access​

Permissions​

Related Features​

Overview

Key Features

Role-Based Access Control

Permission Bundling

Organization Integration

Using Groups

Creating a Group

Listing Groups

Retrieving Group Details

Updating a Group

Partial Update

Deleting a Group

Assigning Users to Groups

Platform-Level Groups

Organization-Level Groups

Permission Management

Finding Available Permissions

Permission Structure

Common Permission Patterns

Common Group Patterns

Read-Only Viewer

Content Manager

Organization Administrator

Developer

System Administrator

Best Practices

Use Cases

Multi-Tier Access

Department-Based Access

Project-Based Access

Permissions

Related Features