0
# Groups Service
1

2
Group membership management, access control, and policy configuration for collaborative research with fine-grained permission controls. The Groups service enables creation and management of user groups for organizing access to Globus services and resources with sophisticated membership policies and authentication requirements.
3

4
## Capabilities
5

6
### Groups Client
7

8
Core client for low-level Groups service operations with comprehensive group management, membership control, and policy administration.
9

10
```python { .api }
11
class GroupsClient(BaseClient):
12
    """
13
    Client for Globus Groups API operations.
14
    
15
    Provides low-level access to groups management including group creation,
16
    membership management, and policy configuration. For common operations,
17
    consider using GroupsManager for a simplified interface.
18
    """
19
    
20
    def __init__(
21
        self,
22
        *,
23
        app: GlobusApp | None = None,
24
        authorizer: GlobusAuthorizer | None = None,
25
        environment: str | None = None,
26
        base_url: str | None = None,
27
        **kwargs
28
    ) -> None: ...
29
```
30

31
### Group Management Operations
32

33
Create, retrieve, update, and delete groups with comprehensive configuration options and metadata management.
34

35
```python { .api }
36
def get_my_groups(
37
    self, 
38
    *, 
39
    query_params: dict[str, Any] | None = None
40
) -> ArrayResponse:
41
    """
42
    Get list of groups the authenticated user belongs to.
43
    
44
    Returns all groups where the user has any level of membership
45
    including member, manager, or admin roles.
46
    
47
    Parameters:
48
    - query_params: Additional query parameters
49
    
50
    Returns:
51
    ArrayResponse with list of group memberships
52
    """
53

54
def get_group(
55
    self,
56
    group_id: str | UUID,
57
    *,
58
    include: str | Iterable[str] | None = None,
59
    query_params: dict[str, Any] | None = None
60
) -> GlobusHTTPResponse:
61
    """
62
    Get detailed information about a specific group.
63
    
64
    Parameters:
65
    - group_id: UUID of the group to retrieve
66
    - include: Additional fields to include (memberships, my_memberships, 
67
      policies, allowed_actions, child_ids)
68
    - query_params: Additional query parameters
69
    
70
    Returns:
71
    GlobusHTTPResponse with complete group information
72
    """
73

74
def create_group(
75
    self,
76
    data: dict[str, Any],
77
    *,
78
    query_params: dict[str, Any] | None = None
79
) -> GlobusHTTPResponse:
80
    """
81
    Create a new group.
82
    
83
    Creates a group with specified name, description, and optional
84
    parent group for creating hierarchical group structures.
85
    
86
    Parameters:
87
    - data: Group creation data including name, description, parent_id
88
    - query_params: Additional parameters
89
    
90
    Returns:
91
    GlobusHTTPResponse with created group details
92
    """
93

94
def update_group(
95
    self,
96
    group_id: str | UUID,
97
    data: dict[str, Any],
98
    *,
99
    query_params: dict[str, Any] | None = None
100
) -> GlobusHTTPResponse:
101
    """
102
    Update group metadata and configuration.
103
    
104
    Modifies group properties including name, description, and
105
    other group-level settings.
106
    
107
    Parameters:
108
    - group_id: UUID of group to update
109
    - data: Updated group configuration
110
    - query_params: Additional parameters
111
    
112
    Returns:
113
    GlobusHTTPResponse confirming update
114
    """
115

116
def delete_group(
117
    self,
118
    group_id: str | UUID,
119
    *,
120
    query_params: dict[str, Any] | None = None
121
) -> GlobusHTTPResponse:
122
    """
123
    Delete a group.
124
    
125
    Permanently removes a group and all associated memberships.
126
    This operation cannot be undone.
127
    
128
    Parameters:
129
    - group_id: UUID of group to delete
130
    - query_params: Additional parameters
131
    
132
    Returns:
133
    GlobusHTTPResponse confirming deletion
134
    """
135
```
136

137
### Membership Management
138

139
Manage group memberships including adding/removing members, role assignments, and batch operations for efficient membership administration.
140

141
```python { .api }
142
def get_group_memberships(
143
    self,
144
    group_id: str | UUID,
145
    *,
146
    role: str | None = None,
147
    status: str | None = None,
148
    query_params: dict[str, Any] | None = None
149
) -> ArrayResponse:
150
    """
151
    Get list of group memberships with optional filtering.
152
    
153
    Parameters:
154
    - group_id: UUID of the group
155
    - role: Filter by membership role (member, manager, admin)
156
    - status: Filter by membership status (active, pending, etc.)
157
    - query_params: Additional parameters
158
    
159
    Returns:
160
    ArrayResponse with membership listings
161
    """
162

163
def add_member(
164
    self,
165
    group_id: str | UUID,
166
    identity_id: str,
167
    *,
168
    role: GroupRole | str = GroupRole.member,
169
    query_params: dict[str, Any] | None = None
170
) -> GlobusHTTPResponse:
171
    """
172
    Add a member to a group.
173
    
174
    Adds a user to the group with specified role. The user must
175
    have a valid Globus identity.
176
    
177
    Parameters:
178
    - group_id: UUID of the group
179
    - identity_id: Globus identity ID of user to add
180
    - role: Role to assign (member, manager, admin)
181
    - query_params: Additional parameters
182
    
183
    Returns:
184
    GlobusHTTPResponse confirming membership addition
185
    """
186

187
def remove_member(
188
    self,
189
    group_id: str | UUID,
190
    identity_id: str,
191
    *,
192
    query_params: dict[str, Any] | None = None
193
) -> GlobusHTTPResponse:
194
    """
195
    Remove a member from a group.
196
    
197
    Removes user's membership and all associated permissions
198
    within the group.
199
    
200
    Parameters:
201
    - group_id: UUID of the group
202
    - identity_id: Identity ID of user to remove
203
    - query_params: Additional parameters
204
    
205
    Returns:
206
    GlobusHTTPResponse confirming removal
207
    """
208

209
def update_member_role(
210
    self,
211
    group_id: str | UUID,
212
    identity_id: str,
213
    role: GroupRole | str,
214
    *,
215
    query_params: dict[str, Any] | None = None
216
) -> GlobusHTTPResponse:
217
    """
218
    Update a member's role within a group.
219
    
220
    Changes user's role and associated permissions within
221
    the group structure.
222
    
223
    Parameters:
224
    - group_id: UUID of the group
225
    - identity_id: Identity ID of user
226
    - role: New role to assign
227
    - query_params: Additional parameters
228
    
229
    Returns:
230
    GlobusHTTPResponse confirming role update
231
    """
232

233
def batch_membership_action(
234
    self,
235
    group_id: str | UUID,
236
    data: BatchMembershipActions | dict[str, Any],
237
    *,
238
    query_params: dict[str, Any] | None = None
239
) -> GlobusHTTPResponse:
240
    """
241
    Perform multiple membership operations in a single request.
242
    
243
    Efficiently add, remove, or update multiple members with
244
    a single API call for better performance.
245
    
246
    Parameters:
247
    - group_id: UUID of the group
248
    - data: Batch operations specification
249
    - query_params: Additional parameters
250
    
251
    Returns:
252
    GlobusHTTPResponse with results of batch operations
253
    """
254
```
255

256
### Policy Configuration
257

258
Configure group policies for visibility, membership requirements, authentication assurance, and access controls.
259

260
```python { .api }
261
def set_group_policies(
262
    self,
263
    group_id: str | UUID,
264
    data: GroupPolicies | dict[str, Any],
265
    *,
266
    query_params: dict[str, Any] | None = None
267
) -> GlobusHTTPResponse:
268
    """
269
    Set comprehensive group policies and access controls.
270
    
271
    Configures group visibility, membership requirements, join policies,
272
    and authentication assurance settings.
273
    
274
    Parameters:
275
    - group_id: UUID of the group
276
    - data: Policy configuration including visibility and requirements
277
    - query_params: Additional parameters
278
    
279
    Returns:
280
    GlobusHTTPResponse confirming policy updates
281
    """
282

283
def get_group_policies(
284
    self,
285
    group_id: str | UUID,
286
    *,
287
    query_params: dict[str, Any] | None = None
288
) -> GlobusHTTPResponse:
289
    """
290
    Get current group policies and configuration.
291
    
292
    Returns complete policy settings including visibility,
293
    membership requirements, and authentication settings.
294
    
295
    Parameters:
296
    - group_id: UUID of the group
297
    - query_params: Additional parameters
298
    
299
    Returns:
300
    GlobusHTTPResponse with policy configuration
301
    """
302
```
303

304
### High-Level Groups Manager
305

306
Simplified interface for common group operations with convenient methods and type-safe parameters.
307

308
```python { .api }
309
class GroupsManager:
310
    """
311
    High-level interface for common groups operations.
312
    
313
    Provides simplified methods for group creation, membership management,
314
    and policy configuration with convenient parameter handling and
315
    type hints for common use cases.
316
    """
317
    
318
    def __init__(self, client: GroupsClient | None = None) -> None: ...
319
    
320
    def create_group(
321
        self,
322
        name: str,
323
        description: str,
324
        *,
325
        parent_id: str | UUID | None = None
326
    ) -> GlobusHTTPResponse:
327
        """
328
        Create a group with simplified parameters.
329
        
330
        Parameters:
331
        - name: Group name
332
        - description: Group description
333
        - parent_id: Optional parent group for hierarchical structure
334
        
335
        Returns:
336
        GlobusHTTPResponse with created group details
337
        """
338
    
339
    def set_group_policies(
340
        self,
341
        group_id: str | UUID,
342
        *,
343
        is_high_assurance: bool,
344
        group_visibility: GroupVisibility | str,
345
        group_members_visibility: GroupMemberVisibility | str,
346
        join_requests: bool,
347
        signup_fields: Iterable[GroupRequiredSignupFields | str],
348
        authentication_assurance_timeout: int | None = None
349
    ) -> GlobusHTTPResponse:
350
        """
351
        Set group policies with type-safe parameters.
352
        
353
        Parameters:
354
        - group_id: UUID of the group
355
        - is_high_assurance: Whether group provides high assurance guarantee
356
        - group_visibility: Who can see the group (authenticated, private)
357
        - group_members_visibility: Who can see members (members, managers)
358
        - join_requests: Whether to allow join requests
359
        - signup_fields: Required fields for group signup
360
        - authentication_assurance_timeout: High assurance timeout in seconds
361
        
362
        Returns:
363
        GlobusHTTPResponse confirming policy update
364
        """
365
    
366
    def add_member(
367
        self,
368
        group_id: str | UUID,
369
        identity_id: str,
370
        *,
371
        role: GroupRole | str = GroupRole.member
372
    ) -> GlobusHTTPResponse:
373
        """Add member with simplified interface."""
374
    
375
    def remove_member(
376
        self, 
377
        group_id: str | UUID, 
378
        identity_id: str
379
    ) -> GlobusHTTPResponse:
380
        """Remove member with simplified interface."""
381
    
382
    def batch_add_members(
383
        self,
384
        group_id: str | UUID,
385
        identity_ids: Iterable[str],
386
        *,
387
        role: GroupRole | str = GroupRole.member
388
    ) -> GlobusHTTPResponse:
389
        """
390
        Add multiple members efficiently.
391
        
392
        Uses batch operations to add multiple users to a group
393
        with the same role assignment.
394
        
395
        Parameters:
396
        - group_id: UUID of the group
397
        - identity_ids: List of identity IDs to add
398
        - role: Role to assign to all users
399
        
400
        Returns:
401
        GlobusHTTPResponse with batch operation results
402
        """
403
    
404
    def batch_remove_members(
405
        self,
406
        group_id: str | UUID,
407
        identity_ids: Iterable[str]
408
    ) -> GlobusHTTPResponse:
409
        """
410
        Remove multiple members efficiently.
411
        
412
        Uses batch operations to remove multiple users from
413
        a group in a single API call.
414
        
415
        Parameters:
416
        - group_id: UUID of the group
417
        - identity_ids: List of identity IDs to remove
418
        
419
        Returns:
420
        GlobusHTTPResponse with batch operation results
421
        """
422
```
423

424
### Data Classes and Enums
425

426
Type-safe data structures and enumerations for group configuration and membership management.
427

428
```python { .api }
429
class GroupRole(Enum):
430
    """Enumeration of group membership roles."""
431
    member = "member"
432
    manager = "manager" 
433
    admin = "admin"
434

435
class GroupVisibility(Enum):
436
    """Enumeration of group visibility settings."""
437
    authenticated = "authenticated"  # Visible to all authenticated users
438
    private = "private"              # Visible only to members
439

440
class GroupMemberVisibility(Enum):
441
    """Enumeration of member visibility settings."""
442
    members = "members"     # All members can see membership list
443
    managers = "managers"   # Only managers/admins can see membership
444

445
class GroupRequiredSignupFields(Enum):
446
    """Enumeration of fields that can be required for group signup."""
447
    institution = "institution"
448
    current_project_name = "current_project_name"
449
    address = "address"
450
    city = "city"
451
    state = "state"
452
    country = "country"
453
    address1 = "address1"
454
    address2 = "address2"
455
    zip = "zip"
456
    phone = "phone"
457
    department = "department"
458

459
class GroupPolicies(PayloadWrapper):
460
    """
461
    Container for group policy configuration.
462
    
463
    Defines group behavior including visibility, membership requirements,
464
    authentication assurance, and join policies.
465
    """
466
    
467
    def __init__(
468
        self,
469
        *,
470
        is_high_assurance: bool | MissingType = MISSING,
471
        group_visibility: GroupVisibility | str | MissingType = MISSING,
472
        group_members_visibility: GroupMemberVisibility | str | MissingType = MISSING,
473
        join_requests: bool | MissingType = MISSING,
474
        signup_fields: (
475
            Iterable[GroupRequiredSignupFields | str] | MissingType
476
        ) = MISSING,
477
        authentication_assurance_timeout: int | MissingType = MISSING
478
    ) -> None: ...
479

480
class BatchMembershipActions(PayloadWrapper):
481
    """
482
    Container for batch membership operations.
483
    
484
    Defines multiple membership changes to be applied in a single
485
    operation for efficient group management.
486
    """
487
    
488
    def __init__(self) -> None: ...
489
    
490
    def add_members(
491
        self, 
492
        identity_ids: Iterable[str], 
493
        *, 
494
        role: GroupRole | str = GroupRole.member
495
    ) -> BatchMembershipActions:
496
        """Add multiple members with specified role."""
497
    
498
    def remove_members(self, identity_ids: Iterable[str]) -> BatchMembershipActions:
499
        """Remove multiple members."""
500
    
501
    def update_member_roles(
502
        self, 
503
        updates: dict[str, GroupRole | str]
504
    ) -> BatchMembershipActions:
505
        """Update roles for multiple members."""
506
```
507

508
### Error Handling
509

510
Groups-specific error handling for membership and policy management operations.
511

512
```python { .api }
513
class GroupsAPIError(GlobusAPIError):
514
    """
515
    Error class for Groups service API errors.
516
    
517
    Provides enhanced error handling for groups-specific error
518
    conditions including membership conflicts and policy violations.
519
    """
520
```
521

522
## Common Usage Patterns
523

524
### Basic Group Creation and Management
525

526
```python
527
from globus_sdk import GroupsManager, GroupVisibility, GroupMemberVisibility
528

529
# Initialize manager (uses default GroupsClient)
530
groups_manager = GroupsManager()
531

532
# Create a research group
533
group_response = groups_manager.create_group(
534
    name="Climate Research Team",
535
    description="Collaborative group for climate data analysis research"
536
)
537
group_id = group_response["id"]
538

539
# Set group policies
540
groups_manager.set_group_policies(
541
    group_id,
542
    is_high_assurance=False,
543
    group_visibility=GroupVisibility.authenticated,
544
    group_members_visibility=GroupMemberVisibility.members,
545
    join_requests=True,
546
    signup_fields=["institution", "department"]
547
)
548

549
print(f"Created group: {group_id}")
550
```
551

552
### Membership Management
553

554
```python
555
# Add individual members
556
groups_manager.add_member(
557
    group_id,
558
    "user1@example.org",
559
    role=GroupRole.member
560
)
561

562
groups_manager.add_member(
563
    group_id,
564
    "admin@example.org", 
565
    role=GroupRole.admin
566
)
567

568
# Batch add multiple researchers
569
researcher_ids = [
570
    "researcher1@university.edu",
571
    "researcher2@university.edu", 
572
    "researcher3@university.edu"
573
]
574

575
groups_manager.batch_add_members(
576
    group_id,
577
    researcher_ids,
578
    role=GroupRole.member
579
)
580

581
# List group members
582
client = groups_manager.client
583
memberships = client.get_group_memberships(group_id)
584
for membership in memberships:
585
    print(f"{membership['identity_name']}: {membership['role']}")
586
```
587

588
### Hierarchical Groups
589

590
```python
591
# Create parent group for organization
592
org_group = groups_manager.create_group(
593
    name="Research Institute",
594
    description="Top-level organizational group"
595
)
596
org_group_id = org_group["id"]
597

598
# Create department subgroups
599
climate_group = groups_manager.create_group(
600
    name="Climate Department",
601
    description="Climate research department",
602
    parent_id=org_group_id
603
)
604

605
bio_group = groups_manager.create_group(
606
    name="Biology Department", 
607
    description="Biology research department",
608
    parent_id=org_group_id
609
)
610

611
# Members of subgroups inherit parent permissions
612
groups_manager.add_member(climate_group["id"], "climate_researcher@example.org")
613
```
614

615
### High Assurance Groups
616

617
```python
618
from globus_sdk import GroupRequiredSignupFields
619

620
# Create high-assurance group for sensitive data
621
secure_group = groups_manager.create_group(
622
    name="Secure Data Access",
623
    description="High assurance group for sensitive research data"
624
)
625

626
# Configure strict policies
627
groups_manager.set_group_policies(
628
    secure_group["id"],
629
    is_high_assurance=True,
630
    group_visibility=GroupVisibility.private,
631
    group_members_visibility=GroupMemberVisibility.managers,
632
    join_requests=False,  # No self-service joining
633
    signup_fields=[
634
        GroupRequiredSignupFields.institution,
635
        GroupRequiredSignupFields.department,
636
        GroupRequiredSignupFields.phone,
637
        GroupRequiredSignupFields.address
638
    ],
639
    authentication_assurance_timeout=3600  # 1 hour timeout
640
)
641

642
# Only admins can add members to high-assurance groups
643
groups_manager.add_member(
644
    secure_group["id"],
645
    "trusted_user@example.org",
646
    role=GroupRole.member
647
)
648
```
649

650
### Batch Operations for Efficiency
651

652
```python
653
from globus_sdk import BatchMembershipActions
654

655
# Large-scale membership changes
656
batch_actions = BatchMembershipActions()
657

658
# Add new cohort of students
659
new_students = [
660
    "student1@university.edu",
661
    "student2@university.edu", 
662
    # ... more students
663
]
664
batch_actions.add_members(new_students, role=GroupRole.member)
665

666
# Promote some existing members to managers
667
promotions = {
668
    "experienced_user1@university.edu": GroupRole.manager,
669
    "experienced_user2@university.edu": GroupRole.manager
670
}
671
batch_actions.update_member_roles(promotions)
672

673
# Remove graduated students
674
graduated_students = [
675
    "graduated1@university.edu",
676
    "graduated2@university.edu"
677
]
678
batch_actions.remove_members(graduated_students)
679

680
# Execute all changes in single operation
681
client = GroupsClient(authorizer=authorizer)
682
result = client.batch_membership_action(group_id, batch_actions)
683
print(f"Batch operation completed: {len(result['responses'])} changes")
684
```
685

686
### Integration with Access Control
687

688
```python
689
# Groups can be used for access control in other Globus services
690
from globus_sdk import TransferClient
691

692
# Use group for collection access control
693
transfer_client = TransferClient(authorizer=authorizer)
694

695
# The group ID can be used in GCS role assignments
696
group_urn = f"urn:globus:groups:id:{group_id}"
697

698
# Example: Grant group access to a collection (this would be done via GCS)
699
# gcs_client.create_role({
700
#     "collection": collection_id,
701
#     "principal": group_urn,
702
#     "principal_type": "group", 
703
#     "role": "reader"
704
# })
705
```
706

707
### Monitoring and Administration
708

709
```python
710
# Get my groups for user dashboard
711
my_groups = client.get_my_groups()
712
for group in my_groups:
713
    print(f"Group: {group['name']} (Role: {group['my_role']})")
714

715
# Get detailed group information including policies
716
group_details = client.get_group(
717
    group_id,
718
    include=["policies", "memberships", "allowed_actions"]
719
)
720

721
print(f"Group policies: {group_details['policies']}")
722
print(f"Member count: {len(group_details['memberships'])}")
723
print(f"Allowed actions: {group_details['allowed_actions']}")
724

725
# Check if user can perform specific actions
726
if "update_group" in group_details["allowed_actions"]:
727
    print("User can update this group")
728
```