Skip to end of metadata
Go to start of metadata

This document describes the UW NetID Web Services REST interface.  The REST API provides access to resources associated with UW NetIDs such as permitted subscriptions and delegated owners and administrators.

Structure of the URIs

URIs for the UW NetID Web Service have the following structure:

  • https://uwnetid.washington.edu/nws/{version}/{resource}[.{type}]

The response format will depend on the Accept: header on the request or the specified {type} which can be .json, .xml or .html.  A null {resource} will produce a menu of supported resources and URI syntax.

Supported versions are:

  • v1 – party line production version
  • v2 – next production version (same as v1 unless specified)
  • v0 – experimental next production version (single instance, same as v2)
  • v0-eval – experimental evaluation version
  • v0-dev – experimental development version
  • v0-test – experimental test version (whim of the day)

Authentication

Authentication to the UW NetID Web Service can be provided by via an SSL certificate or via UW NetID specific authorization key via a cookie or WWW-Authenticate header.  The authorization keys have a limited lifespan and can be acquired by visiting the following URLs:

In each case, the authorization key will be returned in the following cookies:

Cookie Name

Value
uwnetid_session{uwnetid}|{hextime}-{hashvalue}
uwnetid_2nd

{uwnetid}|{hextime}-{hashvalue}

Where the {hextime}-{hashvalue} string is the authorization key.  To prevent cross-site scripting, the uwnetid_session authorization key may also be required to be supplied in the payload of certain posted requests with:

  • "authKey": "{hextime}-{hashvalue}"

Authorization

Personal UW NetIDs

Individual UW NetIDs have implicit permissions to access and update certain fields and values associated with their own UW NetID.  They can also have delegated authorization over other UW NetIDs by virtue of being a member of certain groups.  Each supplemental or departmental shared UW NetID has an associated group of administrators, u_netid_{uwnetid}-admin.  Members of that group have delegated authorization over the supplemental NetID.  Management of the administrator groups for a supplemental UW NetID is provided by the manage page:

  • https://uwnetid.washington.edu/manage/?reguser&altid={uwnetid}

Personal UW NetIDs may also delegate one or more Computing Support Orgs to support them.  Each Support Org, e.g.: the I-School or Nebula, has an associated group of support staff, u_netid_{OU}_support-staff, who gain delegated authorization over the UW NetIDs that have delegated support roles to that Support Org.  Management of the Support Org support staff groups is provided by the support page:

  • https://uwnetid.washington.edu/support/?dashboard&ou={OU}

Additional support staff are given authorization to provide support for certain resources by virtue of effective membership in other ad hoc groups with names of the form u_subman_a-{role}.  For example, membership in the u_subman_a-libraries group allows one to manage certain library related subscriptions for arbitrary UW NetIDs, for example, the one that controls who can access the electronic reservation system.

Certificates

SSL certificates can be authorized in the same way that UW NetIDs can be authorized by putting their CNs into the indicated groups above.  Well, at least the u_subman_a-{role} groups will accept SSL certificates as members.  Someday there may be mechanisms in place to allow you to stuff these certificates into the other groups as well.  If you have a use-case, let us know.

Resources

actas – Assume alternate identity (v1.15.00)

ANY
  1. /nws/v1/actas/{netid}/{resource}/...

The actas resource allows authorized entities to perform operations as if they were running as the specified UW NetID.  This acts as a qualifier for the rest of the URI.  This requires effective membership in the special u_subman_a-altid group. 

admin – Fetch administrators of shared UW NetIDs (v1.16.00, v1.19.03)

get
  1. /nws/v1/uwnetid/{netid}/ admin
post
  1. /nws/v1/uwnetid/{netid}/ admin
payload
KeywordTypeNotes
addAdminstring | arrayAdministrators can be group names or NetIDs.  Normal group prefixes are recognized, but group names can be prefixed with "g:" and NetIDs with "u:" to disambiguate.
delAdminstring | array

The admin resource fetches the list of administrators and owners associated with the specified shared UW NetID or will add or remove administrators.  UW NetIDs must be permitted to the advisory subscription 183 ("Shared NetID Administrator Eligibility") in order to be added as an administrator.  Attempting to add an ineligible UW NetID will result in a failure with no action taken.  Attempting to add a group that contains an ineligible UW NetID as an effective member will result in a warning, but the group will be added; assuming there are no other issues with the request.  This has the same effect as if the ineligible UW NetID was added to group after the group was added to the administrator list.  Warnings will appear in a "messages" array with an internal status value of "250" and an HTTP status of 200.

NB: The post action on the administrators list for a shared NetID has an asynchronous element that may take several seconds to complete.  An immediate fetch of the administrators may not reflect the most recent updates.

Example
command:
GET /nws/v1/uwnetid/ktest17/admin.json

reply:
{
  "uwNetID": "ktest17",
  "adminList": [
    {
      "name": "bart414a",
      "role": "administrator"
    },
    {
      "name": "bart531c",
      "role": "owner"
    },
    {
      "name": "ken",
      "role": "administrator"
    },
    {
      "name": "krl",
      "role": "owner"
    },
    {
      "name": "ssquire",
      "role": "administrator"
    }
  ],
  "timeStamp": "Wed, 18 Feb 2015 16:46:00 -0800"
}
Example Post
command:
POST /nws/v1/uwnetid/ktest17/admin

payload:
{
  "delAdmin": [ "noyd311", "noyd312", "noyd313" ],
  "addAdmin": "noyd410"
}

reply:
{
  "uwNetID": "ktest17",
  "actions": [
    {
      "admin": "noyd311",
      "type": "netid",
      "action": "delete"
    },
    {
      "admin": "noyd312",
      "type": "netid",
      "action": "delete"
    },
    {
      "admin": "noyd313",
      "type": "netid",
      "action": "delete"
    },
    {
      "admin": "noyd410",
      "type": "netid",
      "action": "add"
    }
  ],
  "status": 200,
  "result": "Okay",
  "timeStamp": "Thu, 14 Mar 2019 15:28:44 -0700",
  "duration": 1.547
}


azure - Azure LIcenses (v1.20.06)

get/nws/v1/azure

The azure resource is used to fetch the current table of Azure licenses used by the Office 365/Azure Licenses subscription handler (subscription 250).  This is a static table that only gets updated when new licenses are added or removed.  The fields returned [might] include the following:

KeywordTypeNotes
ordinalintegerThis ordinal can be used to index into the license string that appears in the subscription_data field for subscription 250.  Note that an ordinal for a license [very likely] won't change, but as licenses are eliminated and new ones are introduced an ordinal may end up getting reused at a later time.  Not all ordinals are in use and it's not the same as the index into the azureLicenseList array.
premiumbooleanPremium licenses will be released upon loss of permit so they can be reassigned.  Non-premium licenses go through a notification sequence with a two week delay before being released.
shortstringThe short name associated with the license.
namestringThe SKU name associated with the license.
oIdstringThe guid of the Azure group used for licensing.
skuIdstringThe guid of the actual Azure license.
descstringThe human-readable description of the license offering.
Example Get
command:
GET /nws/v1/azure

reply:
{
  "azureLicenseList": [
    {
      "ordinal": 0,
      "premium": true,
      "short": "D365-CE",
      "name": "DYN365_ENTERPRISE_PLAN1",
      "oId": "004eefe7-4ca3-46e2-99cf-d6a91d5d55dd",
      "skuId": "ea126fc5-a19e-42e2-a731-da9d437bffcf",
      "desc": "Dynamics 365 Customer Engagement Plan"
    },
    {
      "ordinal": 1,
      "premium": true,
      "short": "D365-Team",
      "name": "DYN365_TEAM_MEMBERS",
      "oId": "1ede1058-1853-4305-a255-5e6d8d68994d",
      "skuId": "7ac9fe77-66b7-4e5e-9e46-10eed1cff547",
      "desc": "Dynamics 365 Team Members"
    },
    {
      "ordinal": 3,
      "premium": false,
      "short": "M365-A3",
      "name": "EMS",
      "oId": "fc2cb4e0-685e-4244-a6f1-2a11c3f93a94",
      "skuId": "efccb6f7-5641-4e0e-bd10-b4976e1bf68e",
      "desc": "Enterprise Mobility + Security E3"
    },
          [...]
    {
      "ordinal": 35,
      "premium": false,
      "short": null,
      "name": "POWERFLOW_P1_FACULTY",
      "oId": "03a500c4-c860-4b51-bc8b-5d7f15f80b86",
      "skuId": "a611f643-36d2-4c13-a8bc-f90c752fcee4",
      "desc": "Microsoft PowerApps Plan 1"
    }
  ],
  "timeStamp": "Tue, 30 Jun 2020 15:27:46 -0700",
  "duration": 0.000
}

basic – Operate on Basic Services (v1.17.07)

get
  1. /nws/v1/basic
  2. /nws/v1/uwnetid/{netid}/basic
post
  1. /nws/v1/uwnetid/{netid}/basic

The basic resource is used to activate all the basic services for a particular UW NetID.  The list of Basic Services is defined by the Subscriptions Permission Matrix.  A get will retrieve the list of subscriptions, a post (with no payload required) will perform an activate function on each of the subscriptions.  The activations of unpermitted subscriptions will fail, but this is an expected and acceptable result.


Example Post
command:
POST /nws/v1/uwnetid/ktest17/basic

reply:
{
  "uwNetID": "ktest17",
  "subscriptionList": [
    {
      "subscriptionCode": 100,
      "result": "okay"
    },
    {
      "subscriptionCode": 20,
      "result": "okay"
    },
    {
      "subscriptionCode": 7,
      "result": "okay"
    },
    {
      "subscriptionCode": 34,
      "result": "okay"
    },
    {
      "subscriptionCode": 80,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 81,
      "result": "okay"
    },
    {
      "subscriptionCode": 82,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 85,
      "result": "okay"
    },
    {
      "subscriptionCode": 86,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 88,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 89,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 110,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 59,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 233,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 235,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 237,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 239,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    },
    {
      "subscriptionCode": 241,
      "result": "fail",
      "reasonCode": 7004,
      "reasonText": "subscription not permitted"
    }
  ],
  "timeStamp": "Tue, 06 Jun 2017 07:21:37 -0700"
}


category - Fetch a UW NetID's category list (v1.17.07, v1.18.02)

get/nws/v1/uwnetid/{netid}/category/[{catCodeList}]
post/nws/v1/uwnetid/{netid}/category/[{catCode}] 
payload
Category POST Payload
{
  "categoryCode": {category},
  "instance": {instance},
  "uwNetID": "{netid}",
  "statusCode": {status},
  "categoryList": [
    {
      {catObject1},
      {catObject2},
        ...
      {catObjectN}
    }
  ]
}

The category resource can be used to discover a UW NetID's affiliations and such.  Also, additional ad hoc "source zero" categories can be added or removed with the post payload.

The categories you're authorized to manipulate with the POST method are controlled by the special groups u_subman_a-category_NNN.  If no categoryList is present in the post payload, a single update will be made.  The categoryList array can be specified to make multiple updates, using the outer block and/or URL to act as default values for missing fields.  The (NetID, CategoryCode, sourceCode, Instance) tuple uniquely selects a particular category record.  If not specified, the instance field will default to "1", the sourceCode field is hard-coded to "0" on posts.  The payload on a post must at least contain the statusCode field which can be assigned a value of "1" for current, "3" for former or "-1" to delete the record altogether.

NB: While /nws/ attempts to support them, mango appears to ignore settings for the expiration,  notify_code and notify_date fields.


Example get
command:
GET /nws/v1/uwnetid/bart533/category

reply:
{
  "uwNetID": "bart533",
  "categoryList": [
    {
      "categoryCode": 4,
      "categoryName": "Staff",
      "sourceCode": 1,
      "sourceName": "UW Human Resources",
      "statusCode": 1,
      "statusName": "Active"
    },
    {
      "categoryCode": 45,
      "categoryName": "Full Service Sponsored",
      "expiration": "2018-12-01",
      "notifyCode": 1003,
      "sourceCode": 0,
      "sourceName": "No Source",
      "statusCode": 1,
      "statusName": "Active"
    },
    {
      "categoryCode": 45,
      "categoryName": "Full Service Sponsored",
      "notifyDate": "2009-12-08",
      "sourceCode": 4,
      "sourceName": "Supplemental",
      "statusCode": 3,
      "statusName": "Former"
    },
    {
      "categoryCode": 199,
      "categoryName": "Office 365 Patron",
      "sourceCode": 0,
      "sourceName": "No Source",
      "statusCode": 1,
      "statusName": "Active"
    }
  ],
  "timeStamp": "Wed, 28 Jun 2017 10:04:54 -0700"
}
Example POST
command:
POST /nws/v1/category

payload:
{
  "category": 240,
  "status": 1,
  "categoryList": [
    {"netid": "ktest17"},
    {"netid": "ktest18", "status": 3}
  ]
}

response:
{
  "responseList": [
    {
      "query": {
        "netid": "ktest17"
      },
      "timeStamp": "Fri, 09 Feb 2018 10:07:25 -0800",
      "result": "Success"
    },
    {
      "query": {
        "status": 3,
        "netid": "ktest18"
      },
      "timeStamp": "Fri, 09 Feb 2018 10:07:25 -0800",
      "result": "Success"
    }
  ]
}


cathistory – Fetch category history (v1.20.04)

get
  1. /nws/v1/cathistory/{catCodeList}
  2. /nws/v1/uwnetid/{netid}/cathistory/{catCodeList}

The category history function returns a table of history records for the specified UW NetID and category code.

Example GET
command:
GET /nws/v1/uwnetid/rjletts/cathistory/4,36

response:
{
  "uwNetID": "rjletts",
  "historyList": [
    {
      "UWNetID": "rjletts",
      "validID": "36728824C3BF49EFA85A6AE7B0260DB0",
      "categoryCode": 4,
      "categoryName": "Staff",
      "history": [
        {
          "instance": 0,
          "sourceCode": 1,
          "sourceName": "UW Human Resources",
          "notifyCode": 0,
          "statusCode": 1,
          "statusName": "Active",
          "logname": "shuksan-prod:insvalidation:empnetid/anonymous@ucswww12.admin.washington.edu",
          "updated": "2010-02-04 09:35:10.401152"
        },
        {
          "instance": 1,
          "sourceCode": 1,
          "sourceName": "UW Human Resources",
          "notifyCode": 0,
          "notifyDate": "2018-08-11",
          "statusCode": 2,
          "statusName": "Grace",
          "logname": "INS:registry1:updvalidation:hrpgen/accsys@rasp11.s.uw.edu",
          "updated": "2018-08-11 11:36:45.471979"
        },
        {
          "instance": 0,
          "sourceCode": 1,
          "sourceName": "UW Human Resources",
          "notifyCode": 0,
          "statusCode": 3,
          "statusName": "Former",
          "logname": "UPD:registry1:updvalidation:hrpgen/accsys@rasp11.s.uw.edu",
          "updated": "2018-08-11 11:36:45.473582"
        },
        {
          "instance": 1,
          "sourceCode": 1,
          "sourceName": "UW Human Resources",
          "notifyCode": 0,
          "notifyDate": "2018-08-11",
          "statusCode": 3,
          "statusName": "Former",
          "logname": "UPD:registry1:updcategory:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-01 07:05:43.171521"
        }
      ]
    },
    {
      "UWNetID": "rjletts",
      "validID": "36728824C3BF49EFA85A6AE7B0260DB0",
      "categoryCode": 36,
      "categoryName": "UW-IT Staff",
      "history": [
        {
          "instance": 1,
          "sourceCode": 0,
          "sourceName": "No Source",
          "notifyCode": 0,
          "statusCode": 1,
          "statusName": "Active",
          "logname": "shuksan-prod:inscategory:rdial@netid01.cac.washington.edu",
          "updated": "2010-02-06 09:30:31.578361"
        },
        {
          "instance": 1,
          "sourceCode": 0,
          "sourceName": "No Source",
          "notifyCode": 0,
          "statusCode": 1,
          "statusName": "Active",
          "logname": "shuksan-dev:inscategory:slurp/rasp01@rasp01.cac.washington.edu",
          "updated": "2010-02-06 09:30:32.422300"
        },
        {
          "instance": 1,
          "sourceCode": 0,
          "sourceName": "No Source",
          "notifyCode": 0,
          "statusCode": 1,
          "statusName": "Active",
          "logname": "UPD:registry1:updcategory:rdial@seuss01.s.uw.edu",
          "updated": "2015-12-22 08:18:58.548395"
        },
        {
          "instance": 1,
          "sourceCode": 0,
          "sourceName": "No Source",
          "notifyCode": 0,
          "statusCode": 3,
          "statusName": "Former",
          "logname": "UPD:registry1:updcategory:rdial@seuss01.s.uw.edu",
          "updated": "2018-08-13 09:35:10.026147"
        }
      ]
    }
  ],
  "timeStamp": "Tue, 14 Apr 2020 11:43:10 -0700",
  "duration": 0.366
}


forwarding - Get forwarding options / Set forwarding (v1.17.07)

get
  1. /nws/v1/uwnetid/{netid}/forwarding/[{subCode}]
post
  1. /nws/v1/uwnetid/{netid}/forwarding/[{subCode}]
payload
Forwarding POST payload
{
  "address": "{user}@{domain}|None"
} 


A GET on the forwarding resource retrieves the forwarding options available for the specified UW NetID.  The response will consist of the following value pairs:

KeywordType

Example                                                           

Notes
uwNetIDstring"bart227"The UW NetID being operated on.
globalPermitbooleantrueFalse if the UW NetID is not allowed to have any forwarding record.  The only viable option is "Stop Forwarding."
currentPermitbooleantrueFalse if the current setting is not permitted.
This would indicate that an associated subscription is expired or will expire soon and the forwarding should be changed.
permitbooleantrueSame as currentPermit [deprecated].
reasonstring"Your UW Deskmail Inbox expired on Dec 3, 1993."If the current setting produces a permit field of false, the 'reason' will give some more information as to what's going on.
restrictedbooleanfalseUW Medicine workforce members and clincial students are restricted as to where they can direct their u-forwarding.
This value will let you know if you're working with someone who is so restricted.
allowedbooleantrueThis will only show up if restricted is true.  It indicates whether the current forwarding is in the set of domains
allowed by the UW Medicine rules.
employeebooleantrueTrue if the UW NetID is associated with an active UW HRP source record.
servicestring"Forwarding for bart227@uw.edu"The name of the forwarding service you're working with.
addressstring"bart227@exchange.washington.edu"The actual email address where forwarding is currently pointing.
descriptionstringForwarded to your UW Office 365 InboxThe party line as to what that means.
alsoAlumnibooleantrueIndicates that the user has {netid}@alumni.washington.edu forwarding which will be affected by a change to @uw.edu forwarding.
alumniAddressstringspamwaffles@aol.comThis will appear iff the user's alumni forwarding currently points somewhere other than where the @uw.edu forwarding goes.
alsoMyUWbooleantrueWhen the user's current @uw.edu forwarding is pointing to Outlook Live, changing it must also update the @myuw.net forwarding.
optionsarray

See table below

There is one entry per option to be offered [or not] to the user.

Each option in the options array will contain the following attributes:

KeywordTypeExampleNotes
namestring"UW Deskmail"This is the generic name to be displayed to the user.
addressstring"bart227@bart227.deskmail.washington.edu"If this option is selected, this string should be returned on a post operation.
currentbooleantrueExactly one option will reflect the user's current settings.
permitbooleantrueThis will indicate whether the user is permitted to use this option.  Note that the user's current setting may not be permitted.  An unpermitted option should still be presented to the user in a "disabled" status.  There is no reconciliation that will adjust forwarding in an unpermitted state just because it's not permitted, it has to be corrected manually by the user or staff.
allowedbooleantrueThe allowed keyword will [only] appear if the user is restricted due to UW Medicine rules (see above).  Note that the user's current setting may not be allowed.  There is no reconciliation that will adjust forwarding just because it is directed somewhere that is not allowed.
activebooleantrueThe active keyword indicates that the option corresponds to a service associated with a subscription.  This boolean flag indicates whether the subscription is active or inactive.  Forwarding pointing to inactive subscriptions will automagically be deactivated by reconciliation processes.
genericbooleantrueThe "generic" keyword will only appear on one option.  This keyword indicates that the option should be presented to the user with a text form field allowing an arbitrary email address to be entered.
contactbooleantrueThe "contact" keyword appears on entries that come from the user's email contact addresses.
notesstring"<div class='notes'>{some text}</div>"The notes string will be a series of HTML <div> tags with a class of 'notes' or 'notes alert' that are intended to be displayed with the option when presented to the user.


A POST operation on the forwarding resource accepts a payload with a single attribute of "address" which is either the intended forwarding email address or the keyword "None" to disable email forwarding.  The response to the post will contain some subset of the following attributes:

KeywordTypeExample                                           Notes
uwNetIDstring"bart227"The UW NetID affected.
updatedbooleantrueConfirmation that things worked.
descriptionstringDelivered to your UW G Suite InboxThe description of the forwarding as it appears in the get response.
addressstring"bart227@gamail.uw.edu"The actual forwarding address that was set.
alsoAlumibooleantrueIndicates that the alumni forwarding is also affected (subscription deactivated if active).
alsoMyUWbooleantrueIndicates that the MyUW.net forwarding was also updated.
alsoLegacybooleantrueIndicates that a Legacy Outlook LIve User category record (category 116) was inserted.
failLegacybooleantrueIf true, it indicates that the MyUW.net forwarding was updated, but the insert of the legacy category failed so the subscription will expire.  One of those "this will never happen" type conditions.
errorMessagestring"The email address you provided is not approved for use by UW Medicine workforce members."If there's a problem with the selected email address you'll get an HTTP response of 400 and an appropriate reason to give the user.  If there's an operational problem in setting a valid email address you'll get an HTTP response of 500 with some ugly error message that would likely confuse the user.
Example Get
command:
GET /nws/v1/uwnetid/krl/forwarding

reply:
{
  "uwNetID": "krl",
  "restricted": false,
  "employee": true,
  "service": "Forwarding for @uw.edu",
  "address": "krl@dewey.s.uw.edu",
  "description": "Forwarded to krl@dewey.s.uw.edu",
  "options": [
    {
      "name": "UW Deskmail",
      "address": "krl@krl.deskmail.washington.edu",
      "current": false,
      "permit": true,
      "active": true
    },
    {
      "name": "UW Office 365",
      "address": "krl@exchange.washington.edu",
      "current": false,
      "permit": true,
      "active": true,
      "notes": "<div class='notes'><a href='https://itconnect.uw.edu/connect/email/exchange-online' target='_blank'>Visit IT Connect</a> for more information about Exchange Online.  UW Medicine workforce members and clinical students should <a href='https://depts.washington.edu/uwsom/information-technology/exchange-online-guidance-clinical-staff' target='_blank'>review Exchange Online Guidance for Clinical Staff</a> before choosing this option.</div>"
    },
    {
      "name": "UW Google Apps",
      "address": "krl@gamail.uw.edu",
      "current": false,
      "permit": true,
      "active": true
    },
    {
      "name": "krl@dewey.s.uw.edu",
      "address": "krl@dewey.s.uw.edu",
      "current": true
    },
    {
      "name": "Forward to ken@cac.washington.edu",
      "address": "ken@cac.washington.edu",
      "current": false,
      "contact": true
    },
    {
      "name": "Forward to",
      "generic": true,
      "current": false,
      "notes": "<div class='notes'>UW Medicine workforce members and clinical students at HMC, UWMC, NWH, VMC, or UWNC are prohibited from forwarding their UW Email accounts, except to a UW Medicine approved email system. (A list of approved email systems is on the UW Medicine ITS Security web site: <a target='_blank' href='https://depts.washington.edu/uwmedsec/restricted/resources/approved_email_domains/'>Approved Email Domains</a>.)</div>"
    },
    {
      "name": "Stop Email Forwarding",
      "current": false,
      "permit": false,
      "notes": "<div class='notes'>Messages will be returned to the sender as undeliverable.</div><div class='notes'>This option is not available to employees.</div>"
    }
  ],
  "timeStamp": "Tue, 11 Jul 2017 12:10:17 -0700"
} 


mi - Microsoft Infrastructure (v1.18.02)

get/nws/v1/uwnetid/{netid}/mi
post/nws/v1/uwnetid/{netid}/mi
payload
Post Payload
{
  "uwNetID": "{netid}",
  "authkey": "{session_key_value}",
  "homeDrive": "{string}",
  "homeDirectory": "{string}",
  "profilePath": "{string}",
  "scriptPath": "{string}",
  "loginShell": "{string}",
  "unixHomeDirectory": "{string}"
} 

The mi resource allows support org staff to fetch and manipulate the NETID Domain Settings for their supportees.


password – Set UW NetID passwords (v1.16.00)

get
  1.   /nws/v1/uwnetid/ {netid} /password
reply

A get on the password resource may return an object with the following fields:

KeywordTypeExampleNotes
uwNetIDString"bart131"
netidStatusArray
  • "Admin"
  • "Person"
  • "Other"
  • "Active"
  • "Inactive"
  • "Wanted"
  • "Abandoned"
  • "Disenfranchised"
Each status element that applies may be included in the array.
kerbStatusString
  • "Inactive"
  • "Active"
  • "Disabled"
  • "Expired"
  • "Suspended"
  • "Pending"
  • "Other"
The status of the Kerberos subscription (subscription 60).
kerbPermitBoolean
  • True
  • False
Indicates whether the Kerberos subscription is permitted.  An active but unpermitted Kerberos subscription suggests that the subscription will be expiring soon.
lastChangeTimestamp"Fri, 09 Mar 2018 2018 11:45:30 -0800"The time the password was established or last changed, if known.
minimumLengthInteger8Admin NetIDs have requirements for longer passwords
post
  1. /nws/v1/[uwnetid/ {netid}] /password 
payload
Password POST Payload
{
  "actionList": [
	{
	  "action": action1,
	  "oldPassword": pw1,
      "newPassword": pw2,
      "uwNetID": uwnetid1,
	  "gecos": personalName1,
      "authMethod": method1
    },
	{
	  "action": action2,
	  "oldPassword": pw3,
      "newPassword": pw4,
      "uwNetID": uwnetid2,
	  "gecos": personalName2,
      "authMethod": method2
    }
  ]
}

The password resource will return information about the last password change time, set a new password (action == "Set") or simply test a prospective password against the current password policy (action == "Test").  For a single operation, the actionList container can be eliminated and the UW NetID can be specified on the URI.  The optional gecos field can be used to specify the user's full name, if known, for a couple of the policy tests; e.g., "You cannot use your name as your password."

If the oldPassword field is specified it must match the UW NetID's current password for the "Set" action.  If the oldPassword is not specified the caller must be a member of u_subman_a-password to be authorized to reset an unknown password.  This resource cannot be used to create a new Kerberos principal.  That can be done with an activate of Subscription 60.  The current state of the Kerberos principal subscription and some NetID status flags are filled in in response to a GET on the password resource.  The Set action requires that the kerbStatus field be "Active".

The authMethod field will be logged with the password change so statistics can be generated about who changes their passwords with what methods.  The actual content of the field is TBD and beyond the scope of what NWS cares about, but a few reasonable values might be "User", "SMS", "EMail", "Admin-{netid}", "TSC-{netid}", "Registrar-{netid}", "QnA", "PAC-{source_code}", "EMail-{source_code}", "Shib-{realm}", ...


Example Get
command:
GET /nws/v1/uwnetid/fox/password

reply:
{
  "uwNetID": "fox",
  "netidStatus": [
    "Person",
    "Active"
  ],
  "kerbStatus": "Active",
  "lastChange": "Fri, 11 Sep 2015 14:33:28 -0700",
  "minimumLength": 8,
  "timeStamp": "Tue, 06 Oct 2015 11:40:07 -0700"
}

command:
GET /nws/v1/uwnetid/sadm_ken/password

reply:
{
  "uwNetID": "sadm_ken",
  "netidStatus": [
    "Admin",
    "Active"
  ],
  "kerbStatus": "Active",
  "lastChange": "Fri, 13 May 2011 09:58:56 -0700",
  "minimumLength": 14,
  "timeStamp": "Tue, 06 Oct 2015 11:23:09 -0700"
}

command:
GET /nws/v1/uwnetid/diegob/password

reply:
{
  "uwNetID": "diegob",
  "netidStatus": [
    "Person",
    "Active"
  ],
  "kerbStatus": "Active",
  "lastChange": "Fri, 21 Oct 2016 15:38:20 -0700",
  "lastChangeMed": "Fri, 21 Oct 2016 15:37:41 -0700",
  "expiresMed": "Sat, 18 Feb 2017 15:37:41 -0800",
  "intervalMed": "120d",
  "minimumLength": 8,
  "timeStamp": "Fri, 11 Nov 2016 00:14:30 -0800"
}

command:
GET /nws/v1/uwnetid/badguy/password

reply:
{
  "uwNetID": "badguy",
  "netidStatus": [
    "Person",
    "Active",
    "Disenfranchised"
  ],
  "kerbStatus": "Disabled",
  "lastChange": "Wed, 17 Apr 2013 11:06:07 -0700",
  "minimumLength": 8,
  "timeStamp": "Tue, 06 Oct 2015 11:40:54 -0700"
}
Example Post
command:
POST /nws/v1/password

reply:
{
  "query": {
    "action": "Set",
    "newPassword": "unsafe1",
    "oldPassword": "simple simon",
    "uwNetID": "ktest17",
    "authMethod": "User"
  },
  "timeStamp": "Mon, 27 Jul 2015 17:08:17 -0700",
  "uwNetID": "ktest17",
  "message": "That's not a good password because it is too short - use more characters.",
  "result": 409
}


pwreset - Establish password reset code (v1.19.07)

post/nws/v1/uwnetid/{netid}/pwreset
payload
KeywordTypeDescription
UWNetIDstringUW NetID to affect, required if not specified on URL
authkeystringSession key value, required if using cookie authentication
orgstringOrganization, default: "TSC"
operatorstringOperator UW NetID, required
ttlstringDesired lifetime of PAC, default "2h" (two hours)
reply
KeywordTypeDescription
UWNetIDstringThe UW NetID affected
subscriptionCodeintegerThe password recovery code subscripton (63)
PACstringPassword recovery code
expirestimeRecovery code expiration time
statusinteger200 for success, 400 for failure
resultstring"okay" or "error"
errorMessagestringFailure reason

A post to the pwreset resource will establish or refresh a password reset code, allowing the password to be reset for the target UW NetID.  This function requires "disuser/reuser" permission on the Kerberos subscription.

quota – Fetch disk usages and limits (v1.18.08)

get
  1. nws/v1/uwnetid/{netid}/quota

The quota resource fetches disk usages and limit values for the filesystems that are associated with "The QDF."  Ths includes the NFS mounted filesystems such as Homer home directories, Web Publishing space, and the legendary "U-Drive."

Example quota fetch
command:
GET /nws/v1/uwnetid/bart352/quota.json

reply: 
{
  "uwNetID": "bart352",
  "quotaList": [
    {
      "filesystem": "/nu00",
      "usage": 0.000,
      "quota": 0.0,
      "limit": 0.0,
      "files": 0,
      "fileQuota": 0,
      "fileLimit": 0,
      "galaxy": 7,
      "comment": "Managed Workstation Files"
    },
    {
      "filesystem": "/da00",
      "usage": 0.031,
      "quota": 1024.0,
      "limit": 1229.0,
      "files": 10,
      "fileQuota": 10000,
      "fileLimit": 20000,
      "galaxy": 6,
      "comment": "Student Files and Directories"
    },
    {
      "filesystem": "/hw00",
      "usage": 2178.344,
      "quota": 1024.0,
      "limit": 1229.0,
      "grace": "EXPIRED",
      "files": 3,
      "fileQuota": 10000,
      "fileLimit": 20000,
      "galaxy": 3,
      "comment": "Web pages"
    },
    {
      "filesystem": "/dw00",
      "usage": 0.016,
      "quota": 0.2,
      "limit": 1229.0,
      "files": 2,
      "fileQuota": 10000,
      "fileLimit": 20000,
      "galaxy": 3,
      "comment": "Student Web Pages"
    },
    {
      "filesystem": "/ud00",
      "usage": 0.000,
      "quota": 51200.0,
      "limit": 51450.0,
      "files": 2,
      "fileQuota": 10000,
      "fileLimit": 20000,
      "galaxy": 2,
      "comment": "Central File Storage (UDrive)"
    }
  ],
  "limitList": [
    {
      "galaxy": 0,
      "description": "Global",
      "limit": 58872.0,
      "usage": 2178.391
    },
    {
      "galaxy": 1,
      "description": "UW Deskmail",
      "limit": 1024.0,
      "usage": 0.000
    },
    {
      "galaxy": 2,
      "description": "CFS (UDrive)",
      "limit": 51200.0,
      "usage": 0.000
    },
    {
      "galaxy": 3,
      "description": "Web Publishing",
      "limit": 1024.0,
      "usage": 2178.359
    },
    {
      "galaxy": 4,
      "description": "Streaming Media",
      "limit": 3000.0,
      "usage": 0.000
    },
    {
      "galaxy": 6,
      "description": "Unix Shell",
      "limit": 1024.0,
      "usage": 0.031
    },
    {
      "galaxy": 7,
      "description": "Nebula",
      "limit": 0.0,
      "usage": 0.000
    },
    {
      "galaxy": 10,
      "description": "Webfiles",
      "limit": 1600.0,
      "usage": 0.000
    }
  ],
  "timeStamp": "Wed, 12 Sep 2018 08:41:51 -0700"
}


radius – Fetch RADIUS authorizations (v1.16.00)

get
  1. /nws/v1/uwnetid/{netid}/radius

The radius resource fetches radius authorizations for the specified UW NetID.

Example
command:
GET /nws/v1/uwnetid/atos/radius.json

reply:
{
  "uwNetID": "atos",
  "Eduroam": "allowed",
  "UW-IT Radius": "allowed",
  "Gigapop": "privileged",
  "K20": "privileged",
  "ONS": "disallowed",
  "UW": "privileged",
  "UW Security": "privileged",
  "Pacific Wave": "privileged",
  "Transit Rail": "privileged",
  "UW Level2": "privileged",
  "Airwave": "admin",
  "VoIP": "disallowed",
  "WPA2 WiFi": "general",
  "timeStamp": "Wed, 18 Feb 2015 16:54:23 -0800"
}

renew - Extend Expiring/Expired Subscriptions (v1.19.02)

post
  1. /nws/v1/uwnetid/{netid}/renew
payload
KeywordTypeNotes
uwNetIDstringThe uwNetID parameter in the payload will override the UW NetID on the URL if specified.  One or the other is required.
categoryarrayA list of integer categories, or a single integer category, must be specified.
extendDaysintegerThe number of days, from zero up to one year, to extend expiring subscriptions must be specified.
responseSee the reponse from "setname" below.

The renew function, which requires "disuser" permission on the Kerberos subscription, adds a number of category records to the user in "Grace" state and then attempts to activate or reactivate expired subscriptions as appropriate.  The subscriptions matrix designates each subscription as "extend on renew" or "activate on renew" or not.  If permitted after the grace category is inserted, any subscriptions in expired state and designated as "extend on renew" or in expired or inactive state and designated "activate on renew" will be activated.  Subscriptions successfully [re-]activated will be flagged as "notified" with an expiration date set to the current date plus the number of days specified with the extendDays value.

setname - Change UW NetID (v1.19.01)

post
  1. /nws/v1/uwnetid/{old_netid}/setname
payload
KeywordTypeNotes
oldNetIDstringThe oldNetID parameter in the payload will override the old NetID on the URL if specified.  One or the other is required.
newNetIDstringThe newNetID parameter is required.
forwardDaysintegerSpecifies the number of days to forward email destined to the old NetID's email address(s) to the new NetID.  Use zero for no forwarding.
nonstandardarray

Required if the new NetID is in a non-standard format.

KeywordSignificance
dashesNew NetID contains hyphens
dollarNew NetID contains dollar signs
leadingNew NetID begins with a non-alphabetic character
longNew NetID is longer than eight characters
underscore

New NetID contains underscores

response
KeywordTypeExampleNotes
queryobject
The request payload is echoed back for verification
statusinteger200

An HTTP-like status for the operation, does not necessarily match the response status (e.g.: "250")

StatusMeaning
200Request completed without issue.
250The setname completed, but one or more of the subscription handlers returned an error status.  See "messages" below.
400The request was unacceptable, see "errorMessage".
401The requester is not permitted
4xxOther caller issue
500Unexpected server error, see "errorMessage".
>500Other server issue.
resultstring"Warning"A textual representation of the status value, "Okay", "Warning", or "Error".
errorMessagestring"Invalid character in the new NetID"A textual explanation of the condition that caused the 300+ status value.
messagesarray

[
  "--- Basic rename complete",
  "--- GWS notified",
  "--- Update kerberos",
  "Kerberos update complete",
  "--- Update homer",
  "Rename complete",
  "--- Update Web Publishing",
  "Rename failed",
  "*** MDSsetsubscription() = 7000: Update failed"
  "--- Setname compete"
]

The messages array contains a running dialog of the actions that were performed to accomplish the setname function.

  • Strings starting with three dashes are actions taken.
  • Strings starting with three asterisks are errors encountered.
  • Other strings are output spewed forth from the subscription handlers that may provide additional information about what went right or went wrong.

The setname function, which requires "disuser" permission on the Kerberos subscription, will rename a UW NetID.  This process must be given extra time to complete as it needs to perform a setname action on each of the user's subscriptions.  On a bad day, this could take a minute or more – with no indication that anything is progressing from the point of view of the caller.  Note: If this becomes problematic, we can modify the setname resource to return a "202: Accepted" response with a link to an event queue the caller can subscribe to to get the eventual result of the action.  Alternatively, the resource can perform the basic setname function and return the list of subscriptions requiring the setname action and rely on the caller to perform those actions via the subscription resource below.

subhistory - Fetch subscription history information (v1.20.04)

get
  1. /nws/v1/subhistory/{subCodeList}
  2. /nws/v1/uwnetid/{netid}/subhistory/{subCodeList}

The subscription history function returns a table of history records for the specified UW NetID and subscription code(s).  Note that the "logname" field in the response should start with "INS" when a record is inserted, unless it was inserted a really long time ago, "UPD" when it gets updated and then "DEL" when the record got deleted.  YMMV.

Example UW G Suite
command:
GET /nws/v1/uwnetid/rjletts/subhistory/144

response:
{
  "uwNetID": "rjletts",
  "historyList": [
    {
      "UWNetID": "rjletts",
      "subscriptionCode": 144,
      "subscriptionName": "UW G Suite",
      "history": [
        {
          "notifyCode": 0,
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "shuksan-prod:setsubscription:manage/140.142.107.82:rjletts@netid04.cac.washington.edu",
          "updated": "2010-12-20 14:48:11.284696"
        },
        {
          "notifyCode": 0,
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry2:setsubscription:manage/67.183.218.6:rjletts@netid12.cac.washington.edu",
          "updated": "2015-01-23 22:05:00.528184"
        },
        {
          "notifyCode": 0,
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry2:setsubscription:manage/140.142.107.82:rjletts@netid11.cac.washington.edu",
          "updated": "2016-01-27 11:05:41.111047"
        },
        {
          "notifyCode": 1,
          "notifyDate": "2018-09-15",
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry1:updsubscription:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-01 07:05:43.602557"
        },
        {
          "notifyCode": 1,
          "notifyDate": "2018-09-15",
          "statusCode": 21,
          "statusName": "Expired Subscription",
          "logname": "UPD:registry2:setsubscription:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-15 07:23:57.864865"
        },
        {
          "notifyCode": 2,
          "notifyDate": "2018-09-15",
          "statusCode": 21,
          "statusName": "Expired Subscription",
          "logname": "UPD:registry2:updsubscription:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-15 07:23:57.884985"
        },
        {
          "notifyCode": 2,
          "notifyDate": "2018-09-15",
          "statusCode": 21,
          "statusName": "Expired Subscription",
          "logname": "DEL:registry2:setsubscription:pwxsubexp@netid12.cac.washington.edu",
          "updated": "2018-11-27 22:56:16.543311"
        }
      ]
    }
  ],
  "timeStamp": "Tue, 14 Apr 2020 12:08:03 -0700",
  "duration": 0.359
}
Example Get Office 365/Azure Licenses
command:
GET /nws/v1/uwnetid/rjletts/subhistory/250

NB: Translation of the subscriptionData fields such as license codes is beyond the scope of this document.

response:
{
  "uwNetID": "rjletts",
  "historyList": [
    {
      "UWNetID": "rjletts",
      "subscriptionCode": 250,
      "subscriptionName": "UW Office 365",
      "history": [
        {
          "subscriptionData": "oid=aac9e432-ada3-4f41-bdd9-19430bf1b51a license=--------A------A--------",
          "notifyCode": 0,
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "INS:registry2:inssubscription:mu/ken@seuss01.s.uw.edu",
          "updated": "2018-07-15 01:41:32.302699"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------A------A--------",
          "notifyCode": 0,
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry1:updsubscription:mu/ken@seuss01.s.uw.edu",
          "updated": "2018-07-18 00:33:22.199054"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------A------A--------",
          "notifyCode": 1,
          "notifyDate": "2018-09-15",
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry1:updsubscription:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-01 07:05:43.582293"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------N------N--------",
          "notifyCode": 1,
          "notifyDate": "2018-09-15",
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry1:updsubscription:nws/128.208.181.43:subman.uwnetid.washi@netid12.cac.washington.edu",
          "updated": "2018-09-04 11:30:24.692892"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------N------N--------",
          "notifyCode": 1,
          "notifyDate": "2018-09-15",
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry2:setsubscription:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-15 07:23:55.926792"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------N------N--------",
          "notifyCode": 2,
          "notifyDate": "2018-09-15",
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry2:updsubscription:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-15 07:23:55.940767"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------C------C--------",
          "notifyCode": 2,
          "notifyDate": "2018-09-15",
          "statusCode": 21,
          "statusName": "Expired Subscription",
          "logname": "UPD:registry2:updsubscription:nws/128.95.155.170:subman.uwnetid.washi@netid11.cac.washington.edu",
          "updated": "2018-09-16 07:15:42.706112"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------C------C--------",
          "notifyCode": 2,
          "notifyDate": "2018-09-15",
          "statusCode": 21,
          "statusName": "Expired Subscription",
          "logname": "UPD:registry1:setsubscription:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-16 07:15:43.142264"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------C------C--------",
          "notifyCode": 2,
          "notifyDate": "2018-09-15",
          "statusCode": 21,
          "statusName": "Expired Subscription",
          "logname": "UPD:registry1:updsubscription:daily2@seuss01.s.uw.edu",
          "updated": "2018-09-16 07:15:43.156203"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=--------E------E--------",
          "notifyCode": 2,
          "notifyDate": "2018-09-15",
          "statusCode": 21,
          "statusName": "Expired Subscription",
          "logname": "UPD:registry1:updsubscription:nws/128.208.181.43:subman.uwnetid.washi@netid11.cac.washington.edu",
          "updated": "2018-09-28 04:24:34.531075"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=------------------------",
          "notifyCode": 0,
          "notifyDate": "2018-09-15",
          "statusCode": 24,
          "statusName": "Inactive Subscription",
          "logname": "UPD:registry1:updsubscription:nws/128.208.181.43:subman.uwnetid.washi@netid11.cac.washington.edu",
          "updated": "2018-10-16 11:31:33.192873"
        },
        {
          "subscriptionData": "oid=cb4acdc0-23a4-415d-9f9e-f636db206518 license=------------------------",
          "notifyCode": 0,
          "notifyDate": "2018-09-15",
          "statusCode": 24,
          "statusName": "Inactive Subscription",
          "logname": "DEL:registry1:delsubscription:mu/ken@seuss01.s.uw.edu",
          "updated": "2018-12-14 10:05:57.902319"
        }
      ]
    }
  ],
  "timeStamp": "Tue, 14 Apr 2020 12:41:15 -0700",
  "duration": 0.407
}
Example GET IDAA History
command:
GET /nws/v1/uwnetid/hbsmith/subhistory/184

NB: The subscriptionData field indicates the version signed and the date it was signed.

response:
{
  "uwNetID": "hbsmith",
  "historyList": [
    {
      "UWNetID": "hbsmith",
      "subscriptionCode": 184,
      "subscriptionName": "Institutional Data Access Agreement",
      "history": [
        {
          "subscriptionData": "1.0 2010-04-05",
          "notifyCode": 0,
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "shuksan-prod:inssubscription:agree/140.142.111.177:hbsmith@netid03.cac.washington.edu",
          "updated": "2010-04-05 11:22:12.473146"
        },
        {
          "subscriptionData": "2.0 2013-02-19",
          "notifyCode": 0,
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "shuksan-prod:updsubscription:agree/69.91.223.219:hbsmith@netid12.cac.washington.edu",
          "updated": "2013-02-19 12:43:22.537482"
        },
        {
          "subscriptionData": "3.0 2020-02-18",
          "notifyCode": 0,
          "statusCode": 20,
          "statusName": "Active Subscription",
          "logname": "UPD:registry1:updsubscription:agree/10.155.119.184:hbsmith@netid12.cac.washington.edu",
          "updated": "2020-02-18 13:06:59.039660"
        }
      ]
    }
  ],
  "timeStamp": "Tue, 14 Apr 2020 12:47:14 -0700",
  "duration": 0.419
}


subscription – Fetch subscription info or perform actions (v1.15.00)

get
  1. /nws/v1/subscription/[{subCodeList}]
  2. /nws/v1/uwnetid/ {netid} /subscription/[{subCodeList}]
post
  1. /nws/v1/uwnetid/ {netid} /subscription/{subCode}
payload
KeywordTypeActionsNotes
actionstringshow, activate, deactivate, suspend, resume, modify, setname, disuser, reuser, permit, unpermit, deny, undeny, adjustSelects the action to be performed on the subscription
actionListarrayall

Allows multiple actions to be performed.  Keywords specified in the elements of the inner array will override keywords specified in the outer layer(s) when applying that action.  The reply will include a responseList array.

categoryintegerpermit, unpermit, deny, undenyDefaults to "0" ("any category")
logForstringactivate (Kerberos only)Specifies the Source and Validation ID as "{src}:{validid}" for UW NetID creation statistics generation
logFromstringactivate (Kerberos only)Specifies the user browser IP address as dotted octets for UW NetID creation statistics generation
dataValuestringactivate, resume, modify, permit, deny, adjustSynonym for subscription's specific "{dataField}" keyword
expiresdatepermit, denyFormats "in {count} {interval}" or "yyyy-mm-dd" accepted.  Defaults to "in 1 year".
notify_codeintegeradjustGenerally 0: clear, 1: notified of expiration, 2: expiration completed, 10: notification requested, 11|12: partial expiration.
notify_datedateadjustShould conform to "yyyy-mm-dd" timestamp format
reallyintegershow, activate, deactivate, suspend, resume, modify, setname, disuser, reuserOverrides "dummy" subscription handler in eval
reasonstringdisuserSpecifies a reason (code) for why the subscription was disabled
replacebooleanpermit, denyOverwrites potential existing permit/deny record
sponsorstringpermit, denyMust exist as UW NetID – defaults to acting NetID
statusintegerpermit, unpermit, deny, undeny

Category status; accepts 0: "Any", 1: "Current" (default), 2: "Grace", 3: "Former"

statusintegeradjustSubscription status; accepts 20: "Active", 21: 'Expired", 22: "Disusered", 23: "Pending", 24: "Inactive", 25: "Cancelling", 29: "Suspended"
subscriptionCodeintegerall
uwNetIDstringall
zapnssprbooleandisuser (Kerberos only)Clears "NetID Self-Service Password Reset" fields
Subscription POST Payload
{
  "actionList": [
	{
	  "action": action1,
	  "subscriptionCode": subcode1,
	  "uwNetID": uwnetid1,
	  dataField: dataFieldValue1,
	},
	{
	  "action": action2,
	  "subscriptionCode": subcode2,
	  "uwNetID": uwnetid2,
	  dataField: dataFieldValue2,
	}
  ]
}
Response

If an actionList array is specified, the results will be returned in a responseList array.  Each action block will generate a response block:

KeywordTypeExampleNotes
queryobject

{"subscriptionCode": 100,
"action": "show"}

The submitted query is echoed back so the results can be attributed to the proper action block that triggered the response.  Note that secrets in the query should be masked out before logging the response.
resultstring"Unable to process request: subscription not permitted"The result will either be "Success" or an indication of what went wrong.
httpStatusinteger403The computed result of the action, in the range of 200 (success) to 500 (server failure), is returned in the response block.  The final HTTP status will be the maximum of these values.
moreInfostring"<h3>Your UW Deskmail Email Account is <strong>Enabled</strong>.</h3> ..."The text from the subscription handler, suitable to be stuffed into a web page <div> block is returned.  This field may not appear if the action failed before the subscription handler was even invoked or the handler had nothing to say.

The subscription resource fetches information about the indicated subscription list or can be used to perform an action on a specific subscription for the specified UW NetID.  The supplied action can be one of "Show", "Activate", "Deactivate", "Suspend", "Reactivate", "Modify", "Setname", "Disuser" or "Reuser".  The optional {dataField} keyword varies depending on the subscription the action is applied to.

Example Unprivileged GET
command:
GET /nws/v1/actas/ktest17/uwnetid/ktest17/subscription/60,20,100,105,137,41.json

reply:
{
  "uwNetID": "ktest17",
  "subscriptionList": [
    {
      "subscriptionCode": 60,
      "subscriptionName": "A Kerberos Principal",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "dataField": "KPW",
      "permits": [
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current"
        }
      ]
    },
    {
      "subscriptionCode": 20,
      "subscriptionName": "Homer Account",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "actions": [
        "Show",
        "Deactivate",
        "Activate"
      ],
      "permits": [
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current"
        }
      ]
    },
    {
      "subscriptionCode": 100,
      "subscriptionName": "UW Email Inbox",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "actions": [
        "Show",
        "Deactivate",
        "Activate"
      ],
      "permits": [
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current"
        }
      ]
    },
    {
      "subscriptionCode": 105,
      "subscriptionName": "U Forwarding",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "dataField": "FWD",
      "dataValue": "ktest17@ktest17.deskmail.washington.edu",
      "permits": [
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current"
        }
      ]
    },
    {
      "subscriptionCode": 137,
      "subscriptionName": "Web Publishing Limits",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "dataField": "LMT",
      "dataValue": "disk=1024",
      "permits": [
        {
          "type": "permit",
          "mode": "explicit",
          "categoryCode": 0,
          "categoryName": "Any Category",
          "statusCode": 1,
          "statusName": "current",
          "dataValue": "disk=1024"
        },
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 0,
          "categoryName": "Any Category",
          "statusCode": 1,
          "statusName": "current",
          "dataValue": "rate=4.17"
        },
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current",
          "dataValue": "max=1024.0 disk=1024.0"
        }
      ]
    },
    {
      "subscriptionCode": 41,
      "subscriptionName": "Melville Account",
      "permitted": false,
      "statusCode": 101,
      "statusName": "Unpermitted"
    }
  ],
  "timeStamp": "Wed, 18 Feb 2015 17:12:12 -0800"
}
Example Priviledged GET
command:
GET /nws/v1/uwnetid/ktest17/subscription/60,20,100,105,137,41.json

reply:
{
  "uwNetID": "ktest17",
  "subscriptionList": [
    {
      "subscriptionCode": 60,
      "subscriptionName": "A Kerberos Principal",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "actions": [
        "Show",
        "Disuser",
        "Deactivate",
        "Permit",
        "Deny"
      ],
      "dataField": "KPW",
      "permits": [
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current"
        }
      ]
    },
    {
      "subscriptionCode": 20,
      "subscriptionName": "Homer Account",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "actions": [
        "Show",
        "Disuser",
        "Deactivate",
        "Permit",
        "Deny",
        "Activate"
      ],
      "permits": [
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current"
        }
      ]
    },
    {
      "subscriptionCode": 100,
      "subscriptionName": "UW Email Inbox",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "actions": [
        "Show",
        "Disuser",
        "Deactivate",
        "Permit",
        "Deny",
        "Activate"
      ],
      "permits": [
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current"
        }
      ]
    },
    {
      "subscriptionCode": 105,
      "subscriptionName": "U Forwarding",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "actions": [
        "Show",
        "Disuser",
        "Modify",
        "Deactivate",
        "Permit",
        "Deny",
        "Activate"
      ],
      "dataField": "FWD",
      "dataValue": "ktest17@ktest17.deskmail.washington.edu",
      "permits": [
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current"
        }
      ]
    },
    {
      "subscriptionCode": 137,
      "subscriptionName": "Web Publishing Limits",
      "permitted": true,
      "statusCode": 20,
      "statusName": "Active",
      "actions": [
        "Show",
        "Disuser",
        "Modify",
        "Deactivate",
        "Permit",
        "Deny",
        "Activate",
        "Unpermit"
      ],
      "dataField": "LMT",
      "dataValue": "disk=1024",
      "permits": [
        {
          "type": "permit",
          "mode": "explicit",
          "categoryCode": 0,
          "categoryName": "Any Category",
          "statusCode": 1,
          "statusName": "current",
          "dataValue": "disk=1024"
        },
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 0,
          "categoryName": "Any Category",
          "statusCode": 1,
          "statusName": "current",
          "dataValue": "rate=4.17"
        },
        {
          "type": "permit",
          "mode": "implicit",
          "categoryCode": 11,
          "categoryName": "Department",
          "statusCode": 1,
          "statusName": "current",
          "dataValue": "max=1024.0 disk=1024.0"
        }
      ]
    },
    {
      "subscriptionCode": 41,
      "subscriptionName": "Melville Account",
      "permitted": false,
      "statusCode": 101,
      "statusName": "Unpermitted",
      "actions": [
        "Show",
        "Activate",
        "Permit",
        "Deny"
      ]
    }
  ],
  "timeStamp": "Wed, 18 Feb 2015 17:21:55 -0800"
}
Example POST
command:
POST /nws/v1/subscription.json

payload:
{"Action": "activate", "SubscriptionCode": "100", "uwNetID": "ktest17"}

reply:
{
  "query": {
    "Action": "activate",
    "SubscriptionCode": "100",
    "uwNetID": "ktest17"
  },
  "timeStamp": "Fri, 20 Feb 2015 14:47:38 -0800",
  "uwNetID": "ktest17",
  "action": "Activate",
  "result": "Success",
  "moreInfo": "<H3>Your UW Email Inbox is now active.</H3>\n\n<P>  Your UW NetID is <STRONG>ktest17</STRONG>.</P>\n<P>  Your email address is <STRONG>ktest17@uw.edu</STRONG>.</P>\n<P>  Your IMAP/POP server is <STRONG>ktest17.deskmail.washington.edu</STRONG>.</P>\n<P>  Your SMTP server is <STRONG>smtp.washington.edu</STRONG>.</P>"
}
Example POST: Adding/Removing a Permit
POST /nws/v1/subscription.json

{"Action": "permit", "SubscriptionCode": 999, "expires": "1999-12-31", "uwNetID": "ktest17", "category": 0, "sponsor": "ktest16", "status": 1} 

To remove a permit you must match the tuple of ("uwNetID", "SubscriptionCode", "category", "status"):

POST /nws/v1/subscription.json

{"Action": "unpermit", "SubscriptionCode": 999, "uwNetID": "ktest17", "category": 0, "status": 1} 

Example Kerberos Disuser
command:
POST nws/v1/uwnetid/bart354/subscription/60.json

payload:
{"action": "disuser", "zapnsspr": true, "reason": "Compromised by evil spammer"}

reply:
{
  "query": {
    "action": "disuser",
    "zapnsspr": true,
    "reason": "Compromised by evil spammer"
  },
  "timeStamp": "Thu, 28 Jan 2016 14:09:16 -0800",
  "uwNetID": "bart354",
  "action": "Disuser",
  "mangoDat": "MGO_DAT_WEB=1 MGO_DAT_ADMIN=1 MGO_DAT_OPER=subman.uwnetid.washington.edu MGO_DAT_ZAPNSSPR=1 MGO_DAT_reason=(Compromised by email spammer)",
  "result": "Success",
  "moreInfo": "<P>\nRemoval of 3 security questions for <STRONG>bart354</STRONG> completed.\n</P>\n<div>bart354: 15 of 15 NSSPR records removed</div>\n<P>\nDisenfranchisement of <STRONG>bart354</STRONG> completed.\n</P>\n<P>\nDisuser of Kerberos principal <STRONG>bart354</STRONG> was successful.\n</P>"
}

supported – Fetch list of supported UW NetIDs (v1.16.00)

get
  1. /nws/v1/uwnetid/ {netid} /supported/

The supported resource fetches the list of UW NetIDs that the specified UW NetID has some role in supporting.  The role returned could be one of owner, administrator, owner-admin or supporter.

Example supported
command:
GET /nws/v1/uwnetid/jmorris/supported.json

reply:
{
  "uwNetID": "jmorris",
  "supportedList": [
    {
      "name": "a_br11",
      "role": "administrator",
      "netidType": "shared"
    },
    {
      "name": "a_vida_tools",
      "role": "administrator",
      "netidType": "shared"
    },
    {
      "name": "barkills",
      "role": "supporter"
    },
    {
      "name": "cpnebeng",
      "role": "owner",
      "netidType": "shared"
    },
    {
      "name": "eadm_jmorris",
      "role": "owner",
      "netidType": "administrator"
    },
    {
      "name": "emailinf",
      "role": "owner-admin",
      "netidType": "shared"
    },
    {
      "name": "jmorris",
      "role": "supporter"
    },
    {
      "name": "jmorris-admin",
      "role": "owner",
      "netidType": "shared"
    },
    {
      "name": "jmorris2",
      "role": "owner",
      "netidType": "shared"
    },
    {
      "name": "jmorris3",
      "role": "owner",
      "netidType": "shared"
    },
    {
      "name": "kool",
      "role": "supporter"
    },
    {
      "name": "monitoring",
      "role": "owner-admin",
      "netidType": "shared"
    },
    {
      "name": "nebnotic",
      "role": "owner-admin",
      "netidType": "shared"
    },
    {
      "name": "nebula",
      "role": "administrator",
      "netidType": "shared"
    },
    {
      "name": "org-mpe",
      "role": "owner",
      "netidType": "support"
    },
    {
      "name": "org-neb",
      "role": "owner",
      "netidType": "support"
    },
    {
      "name": "org-uwwi",
      "role": "owner",
      "netidType": "support"
    },
    {
      "name": "pcppm",
      "role": "owner-admin",
      "netidType": "shared"
    },
    {
      "name": "pmxtest",
      "role": "owner-admin",
      "netidType": "shared"
    },
    {
      "name": "pppmsrv",
      "role": "owner-admin",
      "netidType": "shared"
    },
    {
      "name": "sadm_jmorris",
      "role": "owner",
      "netidType": "administrator"
    },
    {
      "name": "sophosav",
      "role": "administrator",
      "netidType": "shared"
    },
    {
      "name": "uware",
      "role": "administrator",
      "netidType": "shared",
      "status": "former"
    },
    {
      "name": "uwwi-blog",
      "role": "administrator",
      "netidType": "shared"
    },
    {
      "name": "wadm_jmorris",
      "role": "owner",
      "netidType": "administrator"
    },
    {
      "name": "windowsinfrastructure",
      "role": "administrator",
      "netidType": "shared"
    }
  ],
  "timeStamp": "Fri, 20 Feb 2015 16:11:18 -0800"
}


supporter – Fetch list of support OUs (v1.16.00)

get
  1. /nws/v1/uwnetid/ {netid} /supporter/

The supporter resource fetches the list of support orgs that the specified UW NetID has delegated its support to.  To get a list of supporters would require expanding each of the u_netid_{OU}-support-staff groups and taking the union.

Example supporter
command:
GET /nws/v1/uwnetid/jmorris/supporter.json

reply:
{
  "uwNetID": "jmorris",
  "supporterList": [
    {
      "name": "org-mpe",
      "role": "supporter"
    },
    {
      "name": "org-neb",
      "role": "supporter"
    },
    {
      "name": "org-uwwi",
      "role": "supporter"
    },
    {
      "name": "peeves",
      "role": "supporter"
    }
  ],
  "timeStamp": "Fri, 20 Feb 2015 16:47:55 -0800"
}

uwnetid – Specify UW NetID (v1.15.00)

ANY
  1. /nws/v1/uwnetid/{netid}/{resource}/...

The uwnetid resource specifies the UW NetID that the following resource should apply to.  This acts as a qualifier for the rest of the URI.

version – Fetch version (v1.17.07)

GET
  1. /nws/v1/version

The header lines in this document indicate the version each resource was introduced.  The version resource returns the version of the currently running binary.  Only the resources introduced in earlier versions will be supported.

Example Get
{
  "version": "v1.17.07",
  "timeStamp": "Tue, 11 Jul 2017 10:22:38 -0700"
}











  • No labels