Description

The Google Groups API provided by the UW-Madison Google Workspace 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. Login to the Developer Portal.
2. Create a new App. From the drop-down next under yournetid@wisc.edu, select Apps, then click +New App, or use an existing App if appropriate.
   • If this app is going to be used by a shared group, it is recommended that you create a Team that to share ownership of the app.  Rather than going to the App menu, choose Teams, +New Team, and once created, view the team and select +New App.  Teams can have multiple owners for sharing administration of the app.
3. Locate the APIs section and click Request next to the Google Groups API.
4. Access requires approval from the Google Workspace Team. Email uw-gsuite-support@office365.wisc.edu with a description of your project how it will use the Google Groups API.  Include the App Name and App ID in your request so that it can be appropriately identified.
5. Wait for approval or follow-up questions. The Google Workspace Team will email you when your request has been approved.
6. Obtain a Bearer token from the OAuth API product. Every request to the Google Groups API will require a valid, non-expired Bearer token generated there.
7. Register your application using the POST "/register" end-point within the API.
8. 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 Google Groups API Proxy

Your application will not be able to query the Google Groups APIs directly. Instead, the requests are proxied through API Proxy to handle proper authorization. All query paths should be modified to start with "https://api.wisc.edu/ggroups/...", 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://api.wisc.edu/ggroups/admin/directory/v1/groups (with body content)
• Get group details: GET https://api.wisc.edu/ggroups/admin/directory/v1/groups/mygroup%40g-groups.wisc.edu
• Update group settings: PUT https://api.wisc.edu/ggroups/groups/v1/groups/mygroup%40g-groups.wisc.edu (with body content)

Paths and methods for those paths are shown in API documentation under the "Paths" section. Note that paths many paths include a {variable}, such as {groupEmail}, that needs to be replaced with the appropriate value(s). 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 Google Workspace team.

You must always include Authorization Bearer token obtained from the Developer Portal; 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://api.wisc.edu/ggroups/register" -H "Authorization: Bearer Abcdefghijklmnopqrstuvwxyz"

Create a group

curl -X POST "https://api.wisc.edu/ggroups/admin/directory/v1/groups" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer Abcdefghijklmnopqrstuvwxyz" -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 "Google Workspace" 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. If the Apigee App is owned by the person currently authenticated to the Account Admin site and the app has been registered using POST /register, the application ID will be displayed on the page. You can use the GET /appid route to obtain the application ID. All application IDs follow this format and are immutable:

UNIVERSITYO5603/[owner NetID]@wisc.edu@universityo5603/[original app name]

Notes and Reminders

• API Proxy tokens expire 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 a group in any other domain or change the address of a group to another domain will fail.
• 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.