1. API Overview

This document covers the Globus Groups API that provides a read-only interface to the list of an authenticated user’s groups. All other group information and group management functions are accessed through the Globus web application.

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 Groups API currently supports a single scope: urn:globus:auth:scope:groups.api.globus.org:view_my_groups_and_memberships. It allows the caller to view all the active memberships of the user, and their associated groups.

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.

group_type

String

One of regular or plus.

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.

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.

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.

username

String

The username of the Globus Auth identity.

role

String

One of member, manager, or admin.

4. Endpoints

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

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