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
  }
}