Globus Groups API

Table of Contents

1. API Overview
- 1.1. Domain and Versioning
2. Authentication and Access Control
3. Resources
4. Endpoints

1. API Overview

This document covers the Globus Groups API that provides an interface to the group functions that can be accessed through the Globus Web App. Besides the documentation below, also visit our generated OpenAPI ReDoc documentation that has complete API contracts and additional features not included here.

All API responses are JSON.

1.1. Domain and Versioning

The domain for Globus Groups is groups.api.globus.org. The API is only available via HTTPS. All resources are versioned and prefixed with /v2/.

2. Authentication and Access Control

All API requests must be authenticated using an access token issued by Globus Auth for use with the Groups service. Please note that a Globus Auth token response may contain tokens for multiple services, and therefore clients should ensure that they are using the correct token by inspecting the scope field(s) of the response.

Tokens should be sent in a HTTP Authorization header, like so:

Authorization: Bearer <globus-auth-access-token>

An access token is a scoped, delegated credential. As such, requests are allowed or denied depending on both the scope and the user associated with the token.

Read operations are allowed if they are allowed for any identity (primary or linked) in the user’s Globus Auth identity set.

2.1. Scopes

Apps and services are encouraged to request the narrowest scope which satisfies their requirements.

The specific scopes supported for each endpoint/action are listed in the endpoint descriptions below.

2.2. General Access Control Responses

Globus Groups will return will return HTTP 401 Unauthorized for any call that cannot be authenticated.

If the Authorization: Bearer <globus-access-token> header is missing or malformed the code will be AUTHENTICATION_ERROR.

If the token cannot be validated (e.g. it has expired or been revoked, or if the client accidentally sends a token intended for a different service) the code will be INVALID_TOKEN. Since access tokens are short-lived clients are expected to handle INVALID_TOKEN gracefully, typically by obtaining a new token either via a refresh token or re-authorization.

Requests to view resources which the caller is not permitted to view will return HTTP 404 Not Found, so as to prevent leaking information about the (non-) existence of the resource (such as scanning whether particular identities are members of groups).

Other actions which are not allowed will result in a HTTP 403 Forbidden response.

2.3. Error Responses

All error responses contain at least a code field and a human-readable detail field. For example:

{
  "code": "NOT_FOUND",
  "detail": "The group could not be found, or is not visible."
}

Clients should not attempt to parse or drive logic based on the content of the detail, as it can change at any time.

Specific errors may contain additional fields as needed.

3. Resources

Fields marked as OPTIONAL will not always be returned. This is determined by the endpoint, as described in their specific sections.

3.1. Group

Field	Type	Description
`id`	UUID	The ID of the Globus Group.
`name`	String	The display name of the Globus Group.
`description`	String	The description name of the Globus Group.
`group_type`	String	One of `regular` or `plus`.
`parent_id`	UUID	The ID of the parent of this group.
`child_ids`	Array	A List of group ids that are children of this group.
`enforce_session`	Boolean	Indicates whether or not a user must have a recent authentication with a specific identity in order to make changes to the group. Required for certain high assurance use-cases.
`session_limit`	Integer	Number of seconds required for most recent authentication token.
`session_timeouts`	Mapping	A mapping of identity_ids to data about when that identity’s authentication falls out of this group’s session limit. Only identities in the session will be included here.
`my_memberships` (OPTIONAL)	Array of Membership objects.	The memberships of the currently authenticated user. Typically this will be zero or one elements, but can be more if the user has multiple identities which are all part of the same group.
`memberships` (OPTIONAL)	Array of Membership objects.	The memberships of the group.

3.2. Membership

Field	Type	Description
`identity_id`	UUID	The ID of the Globus Auth identity.
`group_id`	UUID	The ID of the Globus Group.
`source_group_id`	UUID	The ID of the subgroup that caused the membership to be part of the parent.
`username`	String	The username of the Globus Auth identity.
`role`	String	One of `member`, `manager`, or `admin`.
`status`	String	One of `active`, `invited`, `pending`, `rejected`, `removed`, `left` or `declined`.

3.3. Membership Action Error

These are errors for individual actions from bulk updates performed through the edit members on group endpoint.

Field	Type	Description
`identity_id`	UUID	The ID of the Globus Auth identity.
`code`	String	A machine readable code identifying error type.
`detail`	String	A human readable description of the error.

4. Endpoints

We publish OpenAPI specifications for all Groups API endpoints at openapi.json. You can also view up to date ReDoc for the published OpenAPI specification here. It should be noted that endpoints or features described in the OpenAPI specific document that are not covered in this page are considered beta features and subject to change in the future.

4.1. Get My Groups

GET /v2/groups/my_groups

Required scope: urn:globus:auth:scope:groups.api.globus.org:view_my_groups_and_memberships or urn:globus:auth:scope:groups.api.globus.org:all

This endpoint returns, as an array, all groups in which the user is an active member, manager, or admin. The my_memberships field is included by default.

Example response:

[
  {
    "id": "<group-uuid>",
    "name": "A Group",
    "group_type": "regular",
    "enforce_session": false,
    "my_memberships": [
      {
        "group_id": "<group-uuid>",
        "identity_id": "<identity-uuid>",
        "username": "alice@example.com",
        "role": "admin"
      }
    ]
  },
  {
    "id": "<group-uuid>",
    "name": "A Plus Group",
    "group_type": "plus",
    "enforce_session": true,
    "my_memberships": [
      {
        "group_id": "<group-uuid>",
        "identity_id": "<identity-uuid>",
        "username": "alice@university.edu",
        "role": "member"
      },
      {
        "group_id": "<group-uuid>",
        "identity_id": "<identity-uuid>",
        "username": "alice@nationallab.gov",
        "role": "manager"
      }
    ]
  }
]

4.2. Get Group

GET /v2/groups/<group_id>

Required scope: urn:globus:auth:scope:groups.api.globus.org:all

Get details and members of a group by group id. If memberships or my_memberships are in the include parameter and the scopes in the provided authorization token allow memberships to be viewed, the memberships will be returned in the response.

A group can be viewed if:

The group policy is that any authenticated user can view it.
The group is private, and the user has an active/invited/pending membership.

Group memberships can only be viewed by active members. Depending on group policy, this may be further restricted to only admins and managers. Note that future versions may relax this restriction for specific cases, such as allowing invited or pending members to view the membership of the user that invited them.

Example Response:

{
  "name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "group_type": "regular",
  "enforce_session": false,
  "session_limit": 0,
  "session_timeouts": {},
  "my_memberships": [
    {
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1",
      "username": "alice@example.com",
      "role": "member",
      "status": "active"
    }
  ],
  "memberships": [
    {
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1",
      "username": "alice@example.com",
      "role": "member",
      "status": "active"
    }
  ]
}

4.3. Create Group

POST /v2/groups

Required scope: urn:globus:auth:scope:groups.api.globus.org:all

Create a new group with the given name. The effective identity (typically the user’s primary identity) of the Auth token used for the call will be added to the group as an administrator. The group will be created with default polices that:

Allow membership requests only to be approved by admins and managers
Allow subgroups to be created only by admins
Allow the group to be visible only to members
Allow member names to be visible only to managers and admins
Allow invitations to be sent by managers and admins
Disallow requests to join

Example Request Body:

{
  "name": "My Group",
  "description": "A Globus Group"
}

The response is the same as would be received from the Get Group endpoint.

4.4. Update Group

PUT /v2/groups/<group_id>

Required scope: urn:globus:auth:scope:groups.api.globus.org:all

Updates fields on a group. Only members with the admin role can update a group.

Example Request Body:

{
  "name": "My Group",
  "description": "A Globus Group with a new description"
}

4.5. Edit Members On Group

POST /v2/groups/<group_id>

Required scope: urn:globus:auth:scope:groups.api.globus.org:all

This endpoint supports bulk actions on collections of members of the group. More details can be viewed in the generated OpenAPI ReDoc documentation. Currently the following actions are supported:

Accept: Identities in the accept list which are in the users identity set will be accepted into the group. Only invited memberships can accept.
Add: Identities in the "add" list will be added to the group as long as the identity exists and they have not previously left the group, or indicated via settings that they can not be added to any group. Adding an identity which already has an active membership in the group will not modify the membership, and is an error for informational purposes. All active admins and managers are permitted to add members to a group. The response will include the current state of any membership that was successfully processed. The response will also include a list of errors indicating the identity of any requested membership action that failed to be processed.
Approve: Identities in the approve list will be accepted into the group. Only pending memberships can be included in the approve list. All active admins and managers are permitted to approve pending members to a group.
Decline: Identities in the decline list which are in the users identity set will be rejected from the group. Only invited memberships can decline.
Invite: Identities in the invite list will be invited to join the group. All active admins and managers are permitted to invite members to a group. Members may also invite other members if the policy allows it. Role is an optional parameter to set the membership role on invitation.
Join: Identities in the join list which are in the users identity set will join the group, if the group policy is to allow users to join. High Assurance groups cannot use this action.
Leave: Identities in the leave list which are in the users identity set will be removed from the group. Only active memberships can leave. If the identity is the last remaining admin of the group leaving is not allowed, since this would leave the group in an orphaned state.
Reject: Identities in the reject list will be rejected from the group. Only pending memberships can be included in the reject list. All active admins and managers are permitted to reject pending members from a group.
Remove: Identities in the remove list will be removed from the group. Admins can remove admins, managers, and members. Managers can remove managers and members. Regular members cannot remove any members. Only active memberships can be removed, and users cannot remove their own memberships.
Request Join: Identities in the request_join list which are in the users identity set will be set as pending memberships for the group if the group policy requires membership approval. Pending memberships must be approved or rejected by administrators or managers.

Example Request Body:

{
  "add": [
    {
      "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1"
    },
    {
      "identity_id": "9d71854e-0968-11eb-9fd9-af2494b23dfa"
    }
  ],
  "remove": [
    {
      "identity_id": "a11a42b9-62d7-49eb-8328-c2e454af88a1"
    }
  ]
}

Example response:

{
  "add": [
    {
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1",
      "username": "alice@example.com",
      "role": "member",
      "status": "active"
    }
  ],
  "remove": [
    {
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "identity_id": "a11a42b9-62d7-49eb-8328-c2e454af88a1",
      "username": "bob@example.com",
      "role": "member",
      "status": "removed"
    }
  ],
  "errors": {
    "add": [
      {
        "identity_id": "9d71854e-0968-11eb-9fd9-af2494b23dfa",
        "code": "ALREADY_ACTTIVE",
        "detail": "The identity is already an active member of the group."
      }
    ]
  }
}

4.6. Delete Group

DELETE /v2/groups/<group_id>

Required scope: urn:globus:auth:scope:groups.api.globus.org:all

This endpoint allows admins of groups to delete a group.

4.7. Get identity set preferences

GET /v2/preferences

Required scope: urn:globus:auth:scope:groups.api.globus.org:all

This endpoint allows users to get preferences for each of their identities that affect how their identity can be used in groups. Currently, the supported preferences are:

allow_add: Whether or not an identity can be added

The response body is a mapping from identity_id to objects listing preferences.

Example response:

{
  "011a42b9-62d7-49eb-8328-c2e454af88a1": {
    "allow_add": true
  },
  "9d71854e-0968-11eb-9fd9-af2494b23dfa": {
    "allow_add": true
  }
}

4.8. Put identity set preferences

GET /v2/preferences

Required scope: urn:globus:auth:scope:groups.api.globus.org:all

This endpoint allows users to set preferences for each of their identities that affect how their identity can be used in groups. Currently, the supported preferences are:

allow_add: Whether or not an identity can be added

The request body is a mapping from identity_id to objects listing preferences.

Example request:

{
  "011a42b9-62d7-49eb-8328-c2e454af88a1": {
    "allow_add": true
  },
  "9d71854e-0968-11eb-9fd9-af2494b23dfa": {
    "allow_add": true
  }
}