Skip to end of metadata
Go to start of metadata


This guide describes the Groups Web Service (GWS) REST API as used by programmatic clients. It does not describe the user interface offer to browser users.


The GWS REST API is a programmable interface, so you are expected to be an application developer. 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.


The GWS 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 our REST API. Some notes:

  1. Representations may contain additional elements to those describe here.
  2. GET representations are similar to PUT representations.
  3. Many responses include an ETag header.  Where indicated, a corresponding If-Match header with the same data must accompany a PUT request.
  4. Content is identified by a microformat: class, id and type attributes and by text content.  Element names are ignored.

Security and access control


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 GWS must have their DNS name registered in UW DNS.

The GWS also identifies itself with a server certificate issued by the same authority.


  • Authorization decisions are based on the authenticated identity of the client (see Authentication above).
  • In order to edit group information, excluding membership, or to delete a group a client must have Admin privilege on the group.
  • In order to add or remove members a client must have Admin or Update privilege on the group.
  • In order to create a group a client must have Admin or Create privilege on nearest stem of the group.
  • In order to view a group's membership a client must have Admin, Update or Read privilege on the group, or the group must be flagged as "read-all".
  • In order to view the basic information of a group a client must have Admin, Update, Read or View privilege on the group, or the group must be flagged as "read-all" or "view-all".
  • By default, all Personal UW NetIDs have Admin privilege on their own, possibly non-existing, base stem (u_userid).
  • Some clients may assume the privileges of, and act for, another user. This is accomplished by adding an act-as header to a request:

Connection port

Clients are encouraged to connect on the alternate port (7443), as it requests certificate authentication on the initial SSL negotiation. Connecting to port 443 works, but your client will have to be able to handle renegotiation of the connection.  Also note that jumbo frames (MTU > 1500) are not supported.  

Authentication factor

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.

  • This feature is referred to in the GWS UI using an "enable enhanced security" checkbox.
  • The API attribute class is "authnfactor" and has a value of 1 or 2.

However, note that:

  • A group with an authnfactor of 2 cannot be updated via the API.
  • The authnfactor attribute is available starting with API version 2.


A group may be classified, according to the APS 2.6 and UW Data Classification guidelines.

The API attribute class is "classification" and may have the values:

  • 'u' = unclassified
  • 'p' = public
  • 'r' = restricted
  • 'c' = confidential

Note that:

  • GUI access to the membership of confidential groups requires 2-factor authentication.
  • The authnfactor attribute is available starting with API version 2.


  • Direct Members: Groups have several types of direct members:


    A simple UWNetID, e.g. abcde


    A fully qualified eduPersonPrincipalName, e.g.


    A UWCA certificate's common name or subjectAltName, e.g.


    Name of another group, e.g. u_abcde_friends

    UWWIA UWWI machine name
  • Effective members: An effective member is either a direct member of the group or an effective member of a member group

Use of POST

The GWS accepts the POST method for two purposes:

  1. URI too long.
    If your uri would be too long for likely transport to the web service you may enclose it in a POST, with the elements:

    included in the POST document.  The path components of you actual URL must match those in the posted "_uri".

  1. PUT content too big
    If your PUT content would be too big for likely transport to the web service you may enclose it in a POST, with the element:

    included in the POST document.


  • {text} means that "{text}" should be replaced with a specific name or identifier.
  • (root)should be replaced by the base URL of the service. For our production service it is:
  • {type} is a member type: uwnetid|group|dns|eppn|uwwi.

Sample Code

Groups Web Service Resources


GWS supports version v1 and v2. Version 2 supports the authnfactor, classification, membership dependency (dependson), and optin and optout ACLS.

Contact Us: Email to contact the staff in UW-IT who oversee this wiki space and the groups service.


  1. I don't see any mention of response format on this or the sub-pages - maybe I'm just missing it.

    I do have an email exchange from August 2013 in which iam-support stated:

    Currently the only response format is XHTML. We have cadrs in our backlog for XML and JSON, but that work hasn't been prioritized yet.

    Is that still up-to-date information? Either way, it seems worth "publishing" that information in this wiki space.

  2. I have not had the opportunity do do much development with the groups

    service.  However, many of the responses will return plain xml.  Try:

      Accept: text/xml

    Let me know if these would be helpful.  I'll try to get them documented.

    Until we go to 'v3' xhtml has to stay the default format.





  3. That works. I don't mind including headers in my request, so changing the default response format isn't particularly significant for my usage. Now, if you wanted to add JSON, that would be lovely, but I can live with xml.

    I suppose these comments probably do the job, but I think you guys should consider adding a brief paragraph describing the supported formats to the actual documentation (update: seeing that you already indicated you would add docs when you have time). I assume I won't be the last person to wonder.

    Thanks for the reply!