March 27, 2019 – Updated wiki documentation to use "groups.uw.edu" as the production environment; use of "iam-ws.u.washington.edu" is deprecated.
This guide describes the Groups Service REST API (Groups API) as used by programmatic clients. It does not describe the Groups user interface (UI) offered to browser users.
The Groups API is a programmable interface, so you are expected to be an application developer.
The Groups API offers a "RESTful" programmatic interface. It exposes groups and group information as addressable resources via the uniform HTTP interface.
Authorized clients may retrieve (GET), update (PUT) and delete (DELETE) representations of these resources through the API.
Client applications must be able to connect to the web service using HTTPS and authenticate using SSL/TLS authentication with an X.509 certificate.
Some conventions used in our documentation:
text}" should be replaced with a specific name or identifier.
Some conventions used in the API itself:
Clients authenticate with X.509 certificates issued by the UW Services Certificate Authority and are identified by the Subject of the certificate: specifically, the DNS name included in the Common Name (CN) value or any Subject Alt Names.
Hosts connecting to the Groups API must have their DNS name registered in UW DNS.
The Groups API also identifies itself with a server certificate issued by the same authority.
Some clients may assume the privileges of, and act for, another user. This is accomplished by adding an act-as header to a request:
Connecting on port 443 is recommended and required for off campus access. Connecting on the alternate port (7443) is deprecated but supported for legacy campus access. Also note that jumbo frames (MTU > 1500) are not supported.
Your application must be able to connect to the web service using HTTPS and authenticate using SSL/TLS authentication with an X.509 certificate. It must be able to make HTTP GET, PUT, and DELETE requests to the service as needed.
A group may be configured to require 2-factor authentication for update operations including PUT and DELETE operations on the general information, membership, or application information.
authnfactor" and has a value of
However, note that:
2cannot be updated via the API.
A group may be classified according to APS 2.6 and Data Classification Process.
The API attribute class is "
classification" and may have the values:
Direct Members: Groups have several types of direct members:
A simple UWNetID, e.g.
A fully qualified eduPersonPrincipalName, e.g.
A UWCA certificate's common name or subjectAltName, e.g.
Name of another group, e.g.
|MI||A Microsoft Infrastructure AD machine name|
If you are making large membership changes, say more than a few hundred, your experience will be better if you split your activity into adds or deletes of fifty to a hundred members at a time. This tends to give you immediate feedback on successful changes and avoids possible session or connection timeouts.
Groups API supports version v1, v2 and v3 (recommended).
v3 API provides JSON representation and Swagger documentation: Groups Service API v3
v1 and v2 API's provide XML representation. Click here for details.
Email firstname.lastname@example.org to contact the staff in UW-IT who oversee this wiki space and the groups service.
Announcements : Join email@example.com for service announcements.
Discussion : Discuss the service with other customers and users on firstname.lastname@example.org.