UW-Madison G Suite - 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.


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.

Introductory Presentation

An presentation introducing the API with steps to get started can be found at here. Much of the same information provided in the document below is contained in the presentation. You must be signed in with your UW-Madison G Suite account (i.e. bbadger@wisc.edu) to access the presentation.

Link: https://docs.google.com/presentation/d/e/2PACX-1vQtpHtj16EsvvJb6_EfwpyXYKpFQ1j5DIl7C20KLmi_i16nFE7x1R_Xsl8inKF46K976-HI3lmOnIW_/pub?start=false&loop=false&delayms=30000

Getting Access

  1. Obtain access and login to API Store. To get access, follow the directions at https://developer.wisc.edu/subscribe-to-apis/reference/get-access/. When you are granted access to the API Store, access to the GGroups API is granted automatically.
  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 Store 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 Store

Your application will not be able to query the Google Groups APIs directly. Instead, the requests are proxied through API Store 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:

  • Create a group: POST https://gateway.api.wisc.edu/ggroups/v1/admin/directory/v1/groups (with body content)
  • Get group details: GET https://gateway.api.wisc.edu/ggroups/v1/admin/directory/v1/groups/mygroup%40g-groups.wisc.edu
  • Update group settings: PUT https://gateway.api.wisc.edu/ggroups/v1/groups/v1/groups/mygroup%40g-groups.wisc.edu (with body content)

Paths and methods for those paths are shown in API Store 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 Store; 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

  • API Store tokens expire as defined by your application and must be refreshed.
  • There are throttling quotas applied by Google that you may run up against.
  • Adding aliases to groups is prevented at this time.
  • The email address of all groups must be in the "g-groups.wisc.edu" domain. Attempting to create or change the address of a group to another domain will fail.
  • If you change the email address of a group, your application will lose authorization to modify that group and will need to be reapplied.
  • Groups created with the Google Groups API have no owners or members. Unless owners are added, the only way to modify these groups is using the Google Groups API.
  • To leverage this API, you must be full-time faculty/staff, or use an application shared with you by someone who is.

Keywords:google groups api manage store ggroups ggroup   Doc ID:94234
Owner:Jacob F.Group:Google Apps
Created:2019-08-30 16:13 CDTUpdated:2021-09-14 10:00 CDT
Sites:Google Apps
Feedback:  2   0