Google Groups API

This document describes the process for obtaining access to and using the Google Groups API to create and manage Google Groups in the UW-Madison G Suite tenant programmatically.

Description

The Google Groups API provided by the UW-Madison G Suite Team offers campus customers a delegated means of interacting with the Google Groups API. The permissions granted are scoped to only allow modification of Google Groups that have been created by the application or have obtained proper authorization from an owner of the group.


Getting Access

  1. Obtain access and login to API Manager. To request access, send an email to mailteam@office365.wisc.edu. You must be current faculty or staff with an active UW-Madison G Suite account. Please include your NetID with the request.
  2. Create a new application or determine an appropriate existing application
  3. Locate and subscribe the the API titled GGroups (v1) with the application from the previous step
  4. Register your application using the "/register" end-point within the API. You can use the API Console within API Manager or do so programmatically. An example with curl is shown below under "Example query".
  5. Your application should able to query the API immediately

Google API Documentation

Google Groups API: https://developers.google.com/admin-sdk/directory/v1/reference/groups

Google Group Settings API: https://developers.google.com/admin-sdk/groups-settings/v1/reference/groups


Querying through API Manager

Your application will not be able to query the Google Groups APIs directly. Instead, the requests are proxied through API Manager to handle proper authorization. All query paths should be modified to start with "https://gateway.api.wisc.edu/ggroups/v1/", and the remainder of the path follows the Google paradigm, such as "admin/directory/v1/groups" or "groups/v1/groups".

Example paths:

Paths and methods for those paths are shown in API Manager under the “API Console” tab. Note that paths with a * at the end require more and will universally require the group email at a minimum. Except for the modified path above, all paths, parameters, and etc outlined in Google's documentation should function. If you find exceptions or problems, please report them to the G Suite team.

You must always include Authorization Bearer token from API manager; do not attempt to include a Google API Authorization Bearer token. Your application is authorized to create any Google Group (unless it exists already, which returns 409), but the domain must be "g-groups.wisc.edu" or you will receive a "403 Forbidden" result. Your application is authorized to view or modify any group this application has created, but not any other groups.

Example Queries with curl:

Register an application
curl -X POST "https://gateway.api.wisc.edu/ggroups/v1/register" -H "Authorization: Bearer 01234567-890a-bcde-f012-34567890abcd"
Create a group
curl -X POST "https://gateway.api.wisc.edu/ggroups/v1/admin/directory/v1/groups" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer 01234567-890a-bcde-f012-34567890abcd" -d "{ \"email\": \"mygroup@g-groups.wisc.edu\", \"name\" : \"mygroup\", \"description\" : \"My group\"}"

Grant Authorization for existing Google Group

In order for a registered application to view or modify an existing Google Group, the application ID must first be granted access. This can only be done by an existing owner of the group. To add authorization to an application that has been registered (above) for a Google Group that already exists, follow these steps as a user who has the owner role within the Google Group:

  1. Log into the Wisc Account Administration site and select the "Groups API" page in the "G Suite" menu.
  2. Enter the Google Group email address as the "Google Group ID"; e.g. "mygroup@g-groups.wisc.edu"
  3. Enter the Application ID that you want to grant authorization to. This is case-sensitive; e.g. "UNIVERSITYO5603/yournetid@wisc.edu@universityo5603/Hello World"
  4. Click Grant Authorization. Authorization is effective immediately upon success.

The application must be subscribed and registered to the Google Groups API for this to work. The owner of the application will see the authorization(s) granted to their application on the same page.


Notes and Reminders