Creating & Managing Groups

Create groups, global vs local groups, role assignment

Written By jazilkalim

Last updated 3 months ago

What are Groups?

Groups in CampusMindAI are collections of users that share access to specific resources such as VTAs, agents, and content. Groups simplify permission management by allowing administrators to grant access to multiple users simultaneously.

Why Use Groups?

Simplified Access Control: Grant permissions to multiple users at once
Course Organization: Create groups for classes, departments, or projects
Role-Based Access: Combine with user roles for fine-grained permissions
Scalability: Manage hundreds of users efficiently

Group Types

Global Groups (Tenant-Wide)

Scope: Accessible across the entire tenant
Use Case: Department-wide access, organization-level permissions
Created By: Administrators only
Flag: global_group: 1

Local Groups (Resource-Specific)

Scope: Limited to specific resources or contexts
Use Case: Course-specific groups, project teams
Created By: Administrators and Instructors
Flag: global_group: 0

Create Group

Create a new group with specified permissions and scope.

Endpoint Details

Method: POST
URL: {{baseURL}}/api/v1/create_group/
Authentication: Required (JWT Bearer token)

Request Headers

Authorization: Bearer <jwt-token>
Content-Type: application/json

Request Body

			ParameterTypeRequiredDescription
`group_name`	string	Yes	Name of the group
`group_description`	string	Yes	Description of the group's purpose
`global_group`	integer	Yes	0 for local, 1 for global
`role_id`	integer	Yes	Associated role (1=Student, 2=Instructor, 3=Admin)

Example Request

curl -X POST "https://<baseURL>/api/v1/create_group/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_name": "CS101_Fall2024",
    "group_description": "Introduction to Computer Science - Fall 2024",
    "global_group": 0,
    "role_id": 1
  }'

Successful Response

Status Code: 200 OK

{
  "group_data": {
    "group_id": 1000385,
    "group_name": "CS101_Fall2024",
    "group_description": "Introduction to Computer Science - Fall 2024",
    "group_tenant_global": 0,
    "group_created_at": "2024-12-02T10:30:00Z",
    "group_updated_at": "2024-12-02T10:30:00Z",
    "group_created_by": "admin@example.com",
    "group_created_by_id": "550e8400-e29b-41d4-a716-446655440000",
    "group_updated_by": "admin@example.com",
    "group_tenant_id": "d508624f-a0b7-4fd3-9511-05b18ca02784",
    "role_id": 1
  }
}

Response Fields

		FieldTypeDescription
`group_id`	integer	Unique identifier for the group
`group_name`	string	Name of the group
`group_description`	string	Group description
`group_tenant_global`	integer	0=local, 1=global
`group_created_at`	string	Creation timestamp (ISO 8601)
`group_updated_at`	string	Last update timestamp
`group_created_by`	string	Email of creator
`group_created_by_id`	string	User ID of creator
`group_updated_by`	string	Email of last updater
`group_tenant_id`	string	Tenant identifier
`role_id`	integer	Associated role

List Groups

Retrieve a paginated list of groups in your tenant.

Endpoint Details

Method: POST
URL: {{baseURL}}/api/v1/list_group
Authentication: Required (JWT Bearer token)

Request Body

			ParameterTypeRequiredDescription
`page`	integer	Yes	Page number (starts at 1)
`limit`	integer	Yes	Number of groups per page

Example Request

curl -X POST "https://<baseURL>/api/v1/list_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 10
  }'

Response

{
  "current_page": 1,
  "next_page": 2,
  "total_pages": 5,
  "total_records": 47,
  "limit": 10,
  "groups": [
    {
      "group_id": 1000385,
      "group_name": "CS101_Fall2024",
      "group_description": "Introduction to Computer Science - Fall 2024",
      "group_updated_at": "2024-12-02T10:30:00Z",
      "group_tenant_global": "0",
      "group_created_by": "admin@example.com",
      "group_created_by_id": "550e8400-e29b-41d4-a716-446655440000",
      "role_id": 1
    }
  ]
}

Search Groups

Search for groups by name.

Endpoint Details

Method: GET
URL: {{baseURL}}/api/v1/groups?search_term=<term>
Authentication: Required (JWT Bearer token)

Query Parameters

			ParameterTypeRequiredDescription
`search_term`	string	Yes	Search term for group name

Example Request

curl -X GET "https://<baseURL>/api/v1/groups?search_term=CS101" \
  -H "Authorization: Bearer <jwt-token>"

Response

{
  "current_page": 1,
  "next_page": 0,
  "total_pages": 1,
  "total_records": 3,
  "limit": 10,
  "search_term": "CS101",
  "groups": [
    {
      "group_id": 1000385,
      "group_name": "CS101_Fall2024",
      "group_description": "Introduction to Computer Science - Fall 2024",
      "group_updated_at": "2024-12-02T10:30:00Z",
      "group_tenant_global": "0",
      "group_created_by": "admin@example.com",
      "group_created_by_id": "550e8400-e29b-41d4-a716-446655440000",
      "role_id": 1
    }
  ]
}

Delete Group

Remove a group from the system. Users are automatically removed from the group.

Endpoint Details

Method: POST
URL: {{baseURL}}/api/v1/delete_group
Authentication: Required (JWT Bearer token)

Request Body

			ParameterTypeRequiredDescription
`group_id`	integer	Yes	ID of the group to delete

Example Request

curl -X POST "https://<baseURL>/api/v1/delete_group" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": 1000389
  }'

Successful Response

Status Code: 200 OK

{
  "group_id": 0
}

Note: A group_id of 0 indicates successful deletion.

Group Naming Conventions

Best Practices

Course Groups:

[CourseCode]_[Term][Year]
Examples: CS101_Fall2024, MATH201_Spring2025

Department Groups:

[Department]_[Role]
Examples: Engineering_Students, CS_Faculty

Project Groups:

[Project]_[Team/Role]
Examples: AIResearch_Team1, CampusMind_Developers

VTA-Specific Groups:

[VTAName]_[Role]
Examples: AlgebraVTA_Students, BiologyVTA_Instructors

Common Use Cases

Course Setup

Create three groups per course:

# Admin group
{
  "group_name": "CS101_Admin",
  "group_description": "CS101 Administrators",
  "global_group": 0,
  "role_id": 3
}

# Instructor group
{
  "group_name": "CS101_Instructor",
  "group_description": "CS101 Instructors",
  "global_group": 0,
  "role_id": 2
}

# Student group
{
  "group_name": "CS101_Students",
  "group_description": "CS101 Students",
  "global_group": 0,
  "role_id": 1
}

Department-Wide Access

Create global group for department:

{
  "group_name": "Engineering_Faculty",
  "group_description": "All Engineering Department Faculty",
  "global_group": 1,
  "role_id": 2
}

Research Team

Create local group for project:

{
  "group_name": "ML_Research_2024",
  "group_description": "Machine Learning Research Team 2024",
  "global_group": 0,
  "role_id": 2
}

Group Management Workflow

Step 1: Create Group

curl -X POST "https://<baseURL>/api/v1/create_group/" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "group_name": "DataScience_Spring2025",
    "group_description": "Data Science Course Spring 2025",
    "global_group": 0,
    "role_id": 1
  }'

Step 2: Add Users

See "Group Membership" documentation for adding users to groups.

Step 3: Associate with Resources

See "Agent-Group Associations" documentation for linking groups to VTAs and agents.

Step 4: Monitor and Maintain

Regularly review group membership
Update descriptions as needed
Remove inactive groups

Best Practices

Group Creation

Plan Structure:

Define naming convention before creating groups
Document group purposes
Align groups with organizational structure

Start Small:

Create groups as needed, not preemptively
Consolidate similar groups
Avoid redundant groups

Set Clear Descriptions:

Include purpose, scope, and access level
Mention associated courses or projects
Note any special permissions

Group Lifecycle

Creation:

Create at semester/term start
Associate with relevant resources immediately
Add initial members

Maintenance:

Review membership weekly during active term
Remove departing members promptly
Update descriptions as scope changes

Archival:

Keep groups for historical records
Remove active users at term end
Document final state before deletion

Troubleshooting

Group Creation Fails

401 Unauthorized:

Verify JWT token is valid
Check user has appropriate role (Admin or Instructor)

400 Bad Request:

Verify all required fields are provided
Check global_group is 0 or 1
Ensure role_id is 1, 2, or 3

Cannot Find Group

Empty search results:

Verify search term matches group name exactly
Check case sensitivity
Try partial matches
List all groups with pagination

Group Deletion Issues

Group still appears:

Verify deletion response shows group_id: 0
Refresh group list
Check if group was recreated

Cannot delete global group:

Verify you have administrator permissions
Check if group is system-protected

Security Considerations

Permission Requirements

	OperationRequired Role
Create local group	Instructor or Admin
Create global group	Admin only
Delete own group	Instructor (creator) or Admin
Delete any group	Admin only
List groups	All users (see only accessible groups)

Access Control

Global groups grant tenant-wide access
Local groups limit access to specific resources
Users see only groups they belong to or have permission to manage
Group membership doesn't override role restrictions

Audit Trail

Track group operations:

Group creation (who, when, settings)
Membership changes (additions, removals)
Group deletions (who deleted, when)
Access patterns (which resources accessed via group)