Globus Groups

class globus_sdk.GroupsClient(*, environment=None, base_url=None, app=None, app_scopes=None, authorizer=None, app_name=None, transport_params=None)

Bases: BaseClient

Client for the Globus Groups API.

Parameters:

• app (GlobusApp | None) – A GlobusApp which will be used for handling authorization and storing and validating tokens. Passing an app will automatically include a client’s default scopes in the app’s scope requirements unless specific app_scopes are given. If app_name is not given, the app’s app_name will be used. Mutually exclusive with authorizer.

• app_scopes (list[Scope] | None) – Optional list of Scope objects to be added to app’s scope requirements instead of default_scope_requirements. Requires app.

• authorizer (GlobusAuthorizer | None) – A GlobusAuthorizer which will generate Authorization headers. Mutually exclusive with app.

• app_name (str | None) – Optional “nice name” for the application. Has no bearing on the semantics of client actions. It is just passed as part of the User-Agent string, and may be useful when debugging issues with the Globus Team. If both``app`` and app_name are given, this value takes priority.

• base_url (str | None) – The URL for the service. Most client types initialize this value intelligently by default. Set it when inheriting from BaseClient or communicating through a proxy. This value takes precedence over the class attribute of the same name.

• transport_params (dict[str, t.Any] | None) – Options to pass to the transport for this client

This provides a relatively low level client to public groups API endpoints. You may also consider looking at the GroupsManager as a simpler interface to more common actions.

Methods

• batch_membership_action()

• create_group()

• delete_group()

• get_group()

• get_group_by_subscription_id()

• get_group_policies()

• get_identity_preferences()

• get_membership_fields()

• get_my_groups()

• set_group_policies()

• set_identity_preferences()

• set_membership_fields()

• update_group()

scopes: ScopeBuilder | None = <globus_sdk.scopes.builder.ScopeBuilder object>

the scopes for this client may be present as a ScopeBuilder

property default_scope_requirements: list[Scope]

Scopes that will automatically be added to this client’s app’s scope_requirements during _finalize_app.

For clients with static scope requirements this can just be a static value. Clients with dynamic requirements should use @property and must return sane results while the Base Client is being initialized.

get_my_groups(*, query_params=None)

Return a list of groups your identity belongs to.

Parameters:

query_params (dict[str, Any] | None) – Additional passthrough query parameters

Return type:

ArrayResponse

API Info

GET /v2/groups/my_groups

See Retrieve your groups and membership in the API documentation for details.

get_group(group_id, *, include=None, query_params=None)

Get details about a specific group

Parameters:

• group_id (UUID | str) – the ID of the group

• include (None | str | Iterable[str]) – list of additional fields to include (allowed fields are memberships, my_memberships, policies, allowed_actions, and child_ids)

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

GET /v2/groups/<group_id>

See Get Group in the API documentation for details.

get_group_by_subscription_id(subscription_id)

Using a subscription ID, find the group which provides that subscription.

Parameters:

subscription_id (UUID | str) – the subscription ID of the group

Return type:

GlobusHTTPResponse

Example Usage

from globus_sdk import GroupsClient

groups = GroupsClient(...)
group_id = groups.get_group_by_subscription_id(subscription_id)["group_id"]

Example Response Data

{
  "group_id": "07a71d4e-35aa-11f0-af85-1619dd0ed322",
  "subscription_id": "07a71ce0-35aa-11f0-af85-1619dd0ed322",
  "subscription_info": {
    "is_high_assurance": true,
    "is_baa": false,
    "connectors": {
      "052be037-7dda-4d20-b163-3077314dc3e6": {
        "is_ha": true,
        "is_baa": false
      },
      "1b6374b0-f6a4-4cf7-a26f-f262d9c6ca72": {
        "is_ha": true,
        "is_baa": false
      },
      "28ef55da-1f97-11eb-bdfd-12704e0d6a4d": {
        "is_ha": true,
        "is_baa": false
      },
      "49b00fd6-63f1-48ae-b27f-d8af4589f876": {
        "is_ha": true,
        "is_baa": false
      },
      "56366b96-ac98-11e9-abac-9cb6d0d9fd63": {
        "is_ha": true,
        "is_baa": false
      },
      "7251f6c8-93c9-11eb-95ba-12704e0d6a4d": {
        "is_ha": true,
        "is_baa": false
      },
      "7643e831-5f6c-4b47-a07f-8ee90f401d23": {
        "is_ha": true,
        "is_baa": false
      },
      "7c100eae-40fe-11e9-95a3-9cb6d0d9fd63": {
        "is_ha": true,
        "is_baa": false
      },
      "7e3f3f5e-350c-4717-891a-2f451c24b0d4": {
        "is_ha": true,
        "is_baa": false
      },
      "9436da0c-a444-11eb-af93-12704e0d6a4d": {
        "is_ha": true,
        "is_baa": false
      },
      "976cf0cf-78c3-4aab-82d2-7c16adbcc281": {
        "is_ha": true,
        "is_baa": false
      },
      "e47b6920-ff57-11ea-8aaa-000c297ab3c2": {
        "is_ha": true,
        "is_baa": false
      },
      "fb656a17-0f69-4e59-95ff-d0a62ca7bdf5": {
        "is_ha": true,
        "is_baa": false
      }
    }
  }
}

API Info

GET /v2/subscription_info/<subscription_id>

See Get Group by Subscription ID in the API documentation for details.

delete_group(group_id, *, query_params=None)

Delete a group.

Parameters:

• group_id (UUID | str) – the ID of the group

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

DELETE /v2/groups/<group_id>

See Delete a Group in the API documentation for details.

create_group(data, *, query_params=None)

Create a group.

Parameters:

• data (dict[str, Any]) – the group document to create

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

POST /v2/groups

See Create a Group in the API documentation for details.

update_group(group_id, data, *, query_params=None)

Update a given group.

Parameters:

• group_id (UUID | str) – the ID of the group

• data (dict[str, Any]) – the group document to use for update

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

PUT /v2/groups/<group_id>

See Update a Group in the API documentation for details.

get_group_policies(group_id, *, query_params=None)

Get policies for the given group

Parameters:

• group_id (UUID | str) – the ID of the group

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

GET /v2/groups/<group_id>/policies

See Get the policies for a group in the API documentation for details.

set_group_policies(group_id, data, *, query_params=None)

Set policies for the group.

Parameters:

• group_id (UUID | str) – the ID of the group

• data (dict[str, Any] | GroupPolicies) – the group policy document to set

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

PUT /v2/groups/<group_id>/policies

See Set the policies for a group in the API documentation for details.

get_identity_preferences(*, query_params=None)

Get identity preferences. Currently this only includes whether the user allows themselves to be added to groups.

Parameters:

query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

GET /v2/preferences

See Get the preferences for your identity set in the API documentation for details.

set_identity_preferences(data, *, query_params=None)

Set identity preferences. Currently this only includes whether the user allows themselves to be added to groups.

Parameters:

• data (dict[str, Any]) – the identity set preferences document

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

Example Usage

gc = globus_sdk.GroupsClient(...)
gc.set_identity_preferences({"allow_add": False})

API Info

PUT /v2/preferences

See Set the preferences for your identity set in the API documentation for details.

get_membership_fields(group_id, *, query_params=None)

Get membership fields for your identities.

Parameters:

• group_id (UUID | str) – the ID of the group

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

GET /v2/groups/<group_id>/membership_fields

See Get the membership fields for your identity set in the API documentation for details.

set_membership_fields(group_id, data, *, query_params=None)

Set membership fields for your identities.

Parameters:

• group_id (UUID | str) – the ID of the group

• data (dict[Any, str]) – the membership fields document

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

API Info

PUT /v2/groups/<group_id>/membership_fields

See Set the membership fields for your identity set in the API documentation for details.

batch_membership_action(group_id, actions, *, query_params=None)

Execute a batch of actions against several group memberships.

Parameters:

• group_id (UUID | str) – the ID of the group

• actions (dict[str, Any] | BatchMembershipActions) – the batch of membership actions to perform, modifying, creating, and removing memberships in the group

• query_params (dict[str, Any] | None) – additional passthrough query parameters

Return type:

GlobusHTTPResponse

Example Usage

gc = globus_sdk.GroupsClient(...)
group_id = ...
batch = globus_sdk.BatchMembershipActions()
batch.add_members("ae332d86-d274-11e5-b885-b31714a110e9")
batch.invite_members("c699d42e-d274-11e5-bf75-1fc5bf53bb24")
gc.batch_membership_action(group_id, batch)

API Info

PUT /v2/groups/<group_id>/membership_fields

See Perform actions on members of the group in the API documentation for details.

Helper Objects

These helper objects make it easier to create and submit data to a GroupsClient. Additionally, they may be used in concert with the GroupsManager to perform operations.

These enums define values which can be passed to other helpers:

class globus_sdk.GroupMemberVisibility(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

managers = 'managers'

members = 'members'

class globus_sdk.GroupRequiredSignupFields(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

address = 'address'

address1 = 'address1'

address2 = 'address2'

city = 'city'

country = 'country'

current_project_name = 'current_project_name'

department = 'department'

field_of_science = 'field_of_science'

institution = 'institution'

phone = 'phone'

state = 'state'

zip = 'zip'

class globus_sdk.GroupRole(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

admin = 'admin'

manager = 'manager'

member = 'member'

class globus_sdk.GroupVisibility(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

authenticated = 'authenticated'

private = 'private'

Payload Types

A BatchMembershipActions defines how to formulate requests to add, remove, or modify memberships in a group. It can be used to formulate multiple operations to submit in a single request to the service.

class globus_sdk.BatchMembershipActions(dict=None, /, **kwargs)

An object used to represent a batch action on memberships of a group. Perform actions on group members.

accept_invites(identity_ids)

Accept invites for identities. The identities must belong to the identity set of authenticated user.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities for whom to accept invites

Return type:

BatchMembershipActions

add_members(identity_ids, *, role='member')

Add a list of identities to a group with the given role.

Parameters:

• identity_ids (Iterable[UUID | str]) – The identities to add to the group

• role (GroupRole | Literal['member', 'manager', 'admin']) – The role for the new group members

Return type:

BatchMembershipActions

approve_pending(identity_ids)

Approve a list of identities with pending join requests.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to approve as members of the group

Return type:

BatchMembershipActions

decline_invites(identity_ids)

Decline an invitation for a given set of identities.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities for whom invitations should be declined

Return type:

BatchMembershipActions

invite_members(identity_ids, *, role='member')

Invite a list of identities to a group with the given role.

Parameters:

• identity_ids (Iterable[UUID | str]) – The identities to invite to the group

• role (GroupRole | Literal['member', 'manager', 'admin']) – The role for the invited group members

Return type:

BatchMembershipActions

join(identity_ids)

Join a group with the given identities. The identities must be in the authenticated users identity set.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to use to join the group

Return type:

BatchMembershipActions

leave(identity_ids)

Leave a group that one of the identities in the authenticated user’s identity set is a member of.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to remove from the group

Return type:

BatchMembershipActions

reject_join_requests(identity_ids)

Reject identities which have requested to join the group.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to reject from the group

Return type:

BatchMembershipActions

remove_members(identity_ids)

Remove members from a group. This must be done as an admin or manager of the group.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to remove from the group

Return type:

BatchMembershipActions

request_join(identity_ids)

Request to join a group.

Parameters:

identity_ids (Iterable[UUID | str]) – The identities to use to request membership in the group

Return type:

BatchMembershipActions

A GroupPolicies object defines the various policies which can be set on a group. It can be used with the GroupsClient or the GroupsManager.

class globus_sdk.GroupPolicies(*, is_high_assurance, group_visibility, group_members_visibility, join_requests, signup_fields, authentication_assurance_timeout=MISSING)

An object used to represent the policy settings of a group. This may be used to set or modify group settings.

See also: API documentation on setting the policies for the group.

Parameters:

• is_high_assurance (bool) – Whether the group is high assurance or not

• group_visibility (GroupVisibility | Literal['authenticated', 'private']) – The visibility of the group

• group_members_visibility (GroupMemberVisibility | Literal['members', 'managers']) – The visibility of the group members

• join_requests (bool) – Whether the group allows join requests or not

• signup_fields (Iterable[GroupRequiredSignupFields | Literal['institution', 'current_project_name', 'address', 'city', 'state', 'country', 'address1', 'address2', 'zip', 'phone', 'department', 'field_of_science']]) – The fields required for signup in the group

• authentication_assurance_timeout (int | None | utils.MissingType) – The session timeout for high assurance group policy enforcement

High-Level Client Wrappers

The GroupsManager is a high-level helper which wraps a GroupsClient. Many common operations which require assembling a BatchMembershipActions and submitting the result can be achieved with a single method-call on a GroupsManager.

class globus_sdk.GroupsManager(client=None)

A wrapper for the groups client with common membership and group actions wrapped in convenient methods with parameters and type hints.

Methods

• accept_invite()

• add_member()

• approve_pending()

• create_group()

• decline_invite()

• invite_member()

• join()

• leave()

• reject_join_request()

• remove_member()

• request_join()

• set_group_policies()

accept_invite(group_id, identity_id)

Accept invite for an identity. The identity must belong to the identity set of the authenticated user.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity for whom to accept the invite

Return type:

GlobusHTTPResponse

add_member(group_id, identity_id, *, role='member')

Add an identity to a group with the given role.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity to add to the group

• role (GroupRole | Literal['member', 'manager', 'admin']) – The role for the new group member

Return type:

GlobusHTTPResponse

approve_pending(group_id, identity_id)

Approve an identity with a pending join request.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity to approve as a member of the group

Return type:

GlobusHTTPResponse

create_group(name, description, *, parent_id=None)

Create a group with the given name. If a parent ID is included, the group will be a subgroup of the given parent group.

Parameters:

• name (str) – The name of the group

• description (str) – A description of the group

• parent_id (UUID | str | None) – The ID of the parent group, if there is one

Return type:

GlobusHTTPResponse

decline_invite(group_id, identity_id)

Decline an invitation for a given identity.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity for whom to decline the invitation

Return type:

GlobusHTTPResponse

invite_member(group_id, identity_id, *, role='member')

Invite an identity to a group with the given role.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity to invite as a new group member

• role (GroupRole | Literal['member', 'manager', 'admin']) – The role for the invited group member

Return type:

GlobusHTTPResponse

join(group_id, identity_id)

Join a group with the given identity. The identity must be in the authenticated users identity set.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity to use to join the group

Return type:

GlobusHTTPResponse

leave(group_id, identity_id)

Leave a group that one of the identities in the authenticated user’s identity set is a member of.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity to remove from the group

Return type:

GlobusHTTPResponse

reject_join_request(group_id, identity_id)

Reject a member that has requested to join the group.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity to reject from the group

Return type:

GlobusHTTPResponse

remove_member(group_id, identity_id)

Remove a member from a group. This must be done as an admin or manager of the group.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity to remove from the group

Return type:

GlobusHTTPResponse

request_join(group_id, identity_id)

Request to join a group.

Parameters:

• group_id (UUID | str) – The ID of the group

• identity_id (UUID | str) – The identity to use to request membership in the group

Return type:

GlobusHTTPResponse

set_group_policies(group_id, *, is_high_assurance, group_visibility, group_members_visibility, join_requests, signup_fields, authentication_assurance_timeout=None)

Set the group policies for the given group.

Parameters:

• group_id (UUID | str) – The ID of the group on which to set policies

• is_high_assurance (bool) – Whether the group can provide a High Assurance guarantee when used for access controls

• group_visibility (GroupVisibility | Literal['authenticated', 'private']) – The visibility of the group

• group_members_visibility (GroupMemberVisibility | Literal['members', 'managers']) – The visibility of memberships within the group

• join_requests (bool) – Whether the group allows users to request to join

• signup_fields (Iterable[GroupRequiredSignupFields | Literal['institution', 'current_project_name', 'address', 'city', 'state', 'country', 'address1', 'address2', 'zip', 'phone', 'department', 'field_of_science']]) – The required fields for a user to sign up for the group

• authentication_assurance_timeout (int | None) – The timeout used when this group is used to apply a High Assurance authentication guarantee

Return type:

GlobusHTTPResponse

Client Errors

When an error occurs, a GroupsClient will raise this type of error:

class globus_sdk.GroupsAPIError(r, *args, **kwargs)

Bases: GlobusAPIError

Error class for the Globus Groups Service.