This document lists all Middleware REST API operations and describes how to perform them in terms of required and optional inputs and expected outputs. All operations follow a few simple rules:

  1. Most requests require client authentication (HTTP Bearer, client TLS, or HTTP Basic)

  2. The content type of all responses is application/json

  3. Use the appropriate content type for requests that contain entity bodies

    1. Content-Type: application/x-www-form-urlencoded for POST

    2. Content-Type: application/json-patch+json for PATCH

  4. Query result sort order varies by operation but strives for "natural sort order"

  5. 20x status on success

  6. 40x status on client errors (aka "Your Bad")

  7. 50x status on server errors (aka "Our Bad")

Please see the ED REST API Reference for high-level topics such as conventions, authentication, and available resources.

Operations on Resources

Resources can be created, retrieved, updated, and deleted by varying the HTTP method used in an HTTP request:

  1. GET - fetch a resource by ID or query for multiple resources (see subsequent section)

  2. POST - create a new resource

  3. PATCH - update a resource with merge semantics

  4. DELETE - delete a resource

A GET request to the resource collection URI with query parameters is used for a bulk query while a GET to the resource URI is used to fetch a single resource. The following code sample demonstrates the distinction:

# Get a list of Chemistry groups using a "starts with" query and sort results by uugid field
curl $BASE_URL/v1/groups?uugid=chemistry.*&sort=uugid -H"Authorization: Bearer $TOKEN"
# Get the PID account for user hizzy
curl $BASE_URL/v1/accounts/hizzy/pid -H"Authorization: Bearer $TOKEN"

Response Codes

Code Description

200

Successful request that contains a response body. Typical result for fetch and query operations.

201

Successful request that created a new resource. Typical result for POST operations.

204

Successful request that does not contain any content. Typical result for DELETE operations.

400

Client provided invalid data or data that violates a policy.

401

Invalid credentials.

403

Client does not have permission to perform requested operation.

404

The requested resource could not be found.

409

The requested resource already exists.

429

Exceeded some predefined limit; e.g. number of requests, value on a resource.

Querying for Resources

Querystring parameters are used for selecting and limiting bulk query results; these are particular to each type of resource and are discussed in detail for each operation on a resouce. Query parameters are canonically lowercase in keeping with REST API usage guideline #2. As a general rule, the fields that would be expected to be used for searching are supported for searching; for example, selecting groups by manager role or selecting persons by department/organizational unit.

Multiple fields may specified for selecting and filtering bulk queries, and they are combined into a single logicial filter expression as follows:

  • Distinct fields are combined with an AND expression unless otherwise noted (e.g. group roles)

  • Repeat occurrences of the same field are combined with an OR expression

An example should clarify the behavior. Suppose a client wishes to search for all groups that start with either chemistry.nmr or chemistry.chromatography and are managed or administered by user bob. A GET request to the following URL would produce the desired set of groups:

curl $BASE_URL/v1/group?uugid=chemistry.nmr*&uugid=chemistry.chromatography*&manager=bob&administrator=bob \
  -H"Authorization: Bearer $TOKEN"

It’s important to note that group roles have OR semantics, so the distinct manager and administrator fields combine as needed to query for groups in which bob is in either role.

Query Result Pagination

Most query-type endpoints support fetching results in batches of arbitrary size. There are two parameters to control the page and number of results returned: page and size. Pagination parameters are optional, but at least size must be provided when using this facility. Sorting is also supported when using pagination.

Table 1. Request Parameters
Path Type Optional Description

page

Integer

true

Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided.

size

Integer

false

Size of the page you want to retrieve. Must be greater than 0.

sort

String

true

How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order. Example sort options: sort=firstname,asc&sort=lastname,desc.

Creating a New Resource

The POST method MUST be used for resource creation by making a request to the resource collection URI. All parameters used to create a new resource are provided via application/x-www-form-urlencoded. The following example demonstrates resource creation:

# Create group chemistry.chromatographers, which requires both an administrator and contact
payload = {
  'uugid': 'chemistry.chromatographers',
  'contact': 'connie',
  'administrator': 'albert'
}
headers['Content-Type'] = 'application/x-www-form-urlencoded'

# Response contains empty body and resource URI in Location header
response = requests.post(base_url + '/v1/groups', headers=headers, data=payload)
resource_uri = response.headers['Location']

When a resource is created, a 201 Created response is returned with the newly-created resource URI in the Location response header. A separate request to that URI should be made to fetch the new entity.

Error Handling

In the case of an error response, an error document is provided in the response body that provides details on the error(s) that caused the operation to fail. The following code snippets provide examples of single and multiple error cases.

Single Error Example

{
  "code": 400,
  "type": "PidStateException",
  "message": "PID must be in the 'To Be Released' state before it can be removed"
}

Multiple Error Example

{
  "code": 400,
  "type": "MultiErrorException",
  "message": "BannerPIDM(12345)::Incomplete person update due to errors.",
  "details": [
    {
      "label": "Address(BannerAddressType(PR):BannerPhoneType(PR))",
      "message": "Invalid syntax for phone number: 95551939440.  Phone numbers must contain only digits and be exactly 10 digits long.",
      "type": "AddressInputException"
    },
    {
      "label": "Address(BannerAddressType(MA))",
      "message": "Invalid syntax for mailStop: abcd.  Mail stops must contain only digits and be exactly 4 digits long.",
      "type": "AddressInputException"
    }
  ]
}

The items in the details collection may be objects or strings. In the case of an object, both message and type fields are always present; label is optional.

Date Handling

Date fields are represented as ISO 8601 date strings of the format yyyy-MM-dd’T’hh:mm:ssX, where X is the offset in +/-hh:mm syntax. Dates are always reported in the America/New_York time zone where the main Virginia Tech campus resides, which allows clients to ignore the time zone when they are in the same locale and thereby simplify date handling. Some examples of dates provided by GET operations:

  1. 2016-11-30T07:30:01-05:00 (07:30:01AM November 30, 2016 EST)

  2. 2017-01-01T00:01:20-05:00 (12:01:20AM January 1, 2017 EST)

  3. 2017-05-05T17:45:15-04:00 (5:45:15PM May 5, 2017 EDT)

Clients SHOULD provide dates with a time zone when setting dates; if the time zone is omitted, then the America/New_York time zone is assumed. All of the following may be used to indicate the date 12:30:00PM January 1, 2017 EST:

  1. 2017-01-01T12:30:00

  2. 2017-01-01T12:30:00-05:00

  3. 2017-01-01T07:30:00Z

Clients MAY provide dates as an integer for convenience, which will be treated as a Unix timestamp measured in seconds since 1970-01-01T00:00:00Z. Note that this may produce unexpected results as the time will be converted by the system to America/New_York time, resulting in times that are off by 4 or 5 hours unless care is taken to accommodate for time zones on the client system. In many cases, however, such rough accuracy is acceptable when handling expiration dates and similar data elements in the Enterprise Directory.

Account Resource API

Create VT

POST /v2/accounts

Creates a new Virginia Tech account.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Form Parameters

Parameter Optional Description

vtid

false

Virginia Tech ID number of the person who will own the account.

username

false

Account username.

password

false

Account password.

synchronize

true

Flag to determine if the account credential should be synchronized to other systems.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts' -i -X POST \
    -d 'vtid=923456781&username=alice&password=Th3P%40ssword%21&synchronize=true'

Example Response

POST /v2/accounts HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 72

vtid=923456781&username=alice&password=Th3P%40ssword%21&synchronize=true

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 103

{
  "type" : "PolicyException",
  "code" : 400,
  "message" : "User is not eligible for a VT account"
}

Invite Guest

POST /v2/accounts

Invites a guest to create an account by creating an account in UNCREDENTIALED state, then sending an email invitation with a link to the application complete the setup process. The link includes an authentication token that is used to prove ownership of the email account to which the invitation was sent; the destination email address is the identifier of the guest account.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Form Parameters

Parameter Optional Description

email

false

Recipient of the invitation.

inviter

true

Username of the account that initiated the invitation.

message

true

Personalization message to be included in the invitation email.

kv

true

Zero or more pipe-delimited key-value pairs that will be added as metadata in the token.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts' -i -X POST \
    -d 'email=blueberry%40example.com&inviter=inslee&message=Welcome+blue%21'

Example Response

POST /v2/accounts HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 68

email=blueberry%40example.com&inviter=inslee&message=Welcome+blue%21

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid metadata key/value pair"
}

Fetch

GET /v2/accounts/{identifier}

Fetches the account with the given unique identifier - either a Username or an Email.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Path Parameters

Table 2. /v2/accounts/{identifier}
Parameter Description

identifier

Identifier of account to fetch.

Query Parameters

Parameter Optional Description

with

true

Zero or more optional sections of fields to include in fetched account resource.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/alicesocial?with=all' -i -X GET

Example Response

GET /v2/accounts/alicesocial?with=all HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Query

GET /v2/accounts

Fetches a collection of account resources based on query terms.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Query Parameters

Parameter Optional Description

username

true

Identifier (username / email address) of the account

type

true

Type of account

uid

true

UID identifier of the User owning the account

with

true

Zero or more optional sections of fields to include in fetched account resources.

page

true

Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided.

size

true

Size of the page you want to retrieve. Must be greater than 0.

sort

true

How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts?username=the_*&page=3&size=3&sort=checkupDate%2Cdesc&sort=_identifier%2Casc' -i -X GET

Example Response

GET /v2/accounts?username=the_*&page=3&size=3&sort=checkupDate%2Cdesc&sort=_identifier%2Casc HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Add Recovery Option

POST /v2/accounts/{identifier}/recovery_options

Adds a new recovery option or updates an existing option with the given type.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Path Parameters

Table 3. /v2/accounts/{identifier}/recovery_options
Parameter Description

identifier

Identifier of the account that will own the recovery option being set.

Form Parameters

Parameter Optional Description

type

false

Type of recovery option to set.

Must be one of: [ GOOGLE, OTP2SMS, OTP2VOICE, YAHOO ]

endpoint

false

Information required to use the recovery option, such as phone number for OTP2SMS.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/with-new-otp2sms/recovery_options' -i -X POST \
    -d 'type=otp2sms&endpoint=5551234567'

Example Response

POST /v2/accounts/with-new-otp2sms/recovery_options HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 32

type=otp2sms&endpoint=5551234567

Example Set Google Recovery Option Request

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/sasquatch/recovery_options' -i -X POST \
    -d 'type=google&endpoint=222222222222222222222'

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 150

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'bad_type'. Valid types: [ OTP2SMS, OTP2VOICE, GOOGLE, YAHOO ]"
}

Remove Recovery Option

DELETE /v2/accounts/{identifier}/recovery_options/{type}

Deletes the given type of recovery option from the account.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Path Parameters

Table 4. /v2/accounts/{identifier}/recovery_options/{type}
Parameter Description

identifier

Identifier of the account.

type

Type of recovery option to remove.

Must be one of: [ GOOGLE, OTP2SMS, OTP2VOICE, YAHOO ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/remove-otp2sms/recovery_options/OTP2SMS' -i -X DELETE

Example Response

DELETE /v2/accounts/remove-otp2sms/recovery_options/OTP2SMS HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 150

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'bad_type'. Valid types: [ OTP2SMS, OTP2VOICE, GOOGLE, YAHOO ]"
}

Verify Recovery Options

POST /v2/accounts/{identifier}/recovery_options/verify

Verifies the recovery options and updates the checkup date for the given account.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Path Parameters

Table 5. /v2/accounts/{identifier}/recovery_options/verify
Parameter Description

identifier

Identifier of the account to verify.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/verify-ops-pos/recovery_options/verify' -i -X POST

Example Response

POST /v2/accounts/verify-ops-pos/recovery_options/verify HTTP/1.1
Host: api.middleware.vt.edu
Content-Type: application/x-www-form-urlencoded

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Change Password

POST /v2/accounts/{identifier}/password/change

Resets the passphrase for an account. Invokers of this endpoint are required to authenticate the user performing the reset. No authentication is performed by this method.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Path Parameters

Table 6. /v2/accounts/{identifier}/password/change
Parameter Description

identifier

Identifier of account to change.

Form Parameters

Parameter Optional Description

new

false

New password for the account.

credential

false

Token or old password used to authenticate before changing the password.

type

false

Type of credential.

Must be one of: [ GOOGLE, PASSWORD, TOKEN ]

synchronize

true

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/alice/password/change' -i -X POST \
    -d 'new=1B%40dPassword1%21&credential=hKlBlOXm4t2pihzXxm57b22zUuo&type=token&synchronize=true'

Example Response

POST /v2/accounts/alice/password/change HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 89

new=1B%40dPassword1%21&credential=hKlBlOXm4t2pihzXxm57b22zUuo&type=token&synchronize=true

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 99

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Account with ID alice not found"
}

Add Token

POST /v2/accounts/tokens

Generates an TokenScope#AUTHENTICATION scoped token for the account that is the security principal.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Form Parameters

Parameter Optional Description

validity

true

Validity period for the token, if not given set to max validity allowed for the token scope.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/tokens' -i -X POST \
    -d 'validity=PT1H'

Example Response

POST /v2/accounts/tokens HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 13

validity=PT1H

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 146

{
  "type" : "LimitExceededException",
  "code" : 400,
  "message" : "Validity period exceeds maximum allowed for token of scope AUTHENTICATION"
}

Remove Token

DELETE /v2/accounts/tokens

Removes a token from an account where both the account and the token to process are retrieved from the security context.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/tokens' -i -X DELETE

Example Response

DELETE /v2/accounts/tokens HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Unauthorized security issuer"
}

Verify Password

POST /v2/accounts/{identifier}/password/verify

Verifies the active password for a PID account.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/accounts ].

Path Parameters

Table 7. /v2/accounts/{identifier}/password/verify
Parameter Description

identifier

Identifier of the account.

Form Parameters

Parameter Optional Description

pass

false

Active password for the account.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/accounts/verify-pass-pos/password/verify' -i -X POST \
    -d 'pass=Th3P%40ssword%21'

Example Response

POST /v2/accounts/verify-pass-pos/password/verify HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 21

pass=Th3P%40ssword%21

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 102

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Account with ID username not found"
}

Person Completely Updated

POST /v1/replication/banner/consume

Processes a Banner PERSONSET XML message.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/replication-banner ].

Example Request

$ curl 'https://api.middleware.vt.edu/v1/replication/banner/consume' -i -X POST \
    -H 'Content-Type: text/xml;charset=UTF-8' \
    -d '<?xml version="1.0"?>
<PERSONSET>
  <PERSON>
    <BANNER_PIDM>7851451</BANNER_PIDM>
    <VT_IDNUM>916582945</VT_IDNUM>
    <UDC_IDENTIFIER>wynjITOTjVDLgDlMkkNoc6sZpkiRK1On</UDC_IDENTIFIER>
    <SSN_HASH>5j2s1isTALxcpVBXd6hJNUJyOMaYBByXNMR7DOB0irI=</SSN_HASH>
    <NAMESET>
      <BANNERNAME>
        <LASTNAME></LASTNAME>
        <FIRSTNAME></FIRSTNAME>
        <MIDDLENAME>IS</MIDDLENAME>
        <SUFFIX></SUFFIX>
      </BANNERNAME>
    </NAMESET>
    <BIRTHDATE>1990-11-30</BIRTHDATE>
    <CONFIDENTIAL_FLAG>1</CONFIDENTIAL_FLAG>
    <DECEASED_FLAG>0</DECEASED_FLAG>
    <GENDER>M</GENDER>
    <AFFILIATION_DATA>
      <AFFILIATION>VT-ALUM</AFFILIATION>
      <AFFILIATION>VT-ACTIVE-MEMBER</AFFILIATION>
      <AFFILIATION>VT-EMPLOYEE</AFFILIATION>
      <AFFILIATION>VT-EMPLOYEE-STATE</AFFILIATION>
      <AFFILIATION>VT-FACULTY</AFFILIATION>
      <AFFILIATION>VT-STUDENT</AFFILIATION>
    </AFFILIATION_DATA>
    <ADDRESS_SET>
      <ADDRESS TYPE="MA">
        <STREET1>1500 Maple St</STREET1>
        <STREET2>Tree #2</STREET2>
        <STREET3>Limb #1</STREET3>
        <CITY>War</CITY>
        <STATE_CODE>WV</STATE_CODE>
        <POSTALCODE>24892</POSTALCODE>
        <COUNTRY>USA</COUNTRY>
        <UNLISTED_FLAG>1</UNLISTED_FLAG>
        <MAILSTOP></MAILSTOP>
        <PHONESET>
          <PHONE TYPE="MA">
            <NUMBER>5405551212</NUMBER>
            <UNLISTED_FLAG>1</UNLISTED_FLAG>
          </PHONE>
        </PHONESET>
      </ADDRESS>
      <ADDRESS TYPE="OF">
        <STREET1>SETI-Middleware</STREET1>
        <STREET2>1700 Pratt Drive</STREET2>
        <STREET3></STREET3>
        <CITY>Blacksburg</CITY>
        <STATE_CODE>VA</STATE_CODE>
        <POSTALCODE>24060</POSTALCODE>
        <COUNTRY></COUNTRY>
        <UNLISTED_FLAG>0</UNLISTED_FLAG>
        <MAILSTOP>0479</MAILSTOP>
        <PHONESET>
          <PHONE TYPE="OF">
            <NUMBER>5402314357</NUMBER>
            <UNLISTED_FLAG>0</UNLISTED_FLAG>
          </PHONE>
        </PHONESET>
      </ADDRESS>
    </ADDRESS_SET>
    <EMPLOYEE_DATA>
      <EMPLOYEE_TYPE>3A</EMPLOYEE_TYPE>
      <JOB_TITLE>Trouble Maker</JOB_TITLE>
      <EMPLOYEE_STATUS>A</EMPLOYEE_STATUS>
      <HIREDATE>2010-01-01</HIREDATE>
      <TERMDATE></TERMDATE>
      <DEPT>066103</DEPT>
      <CONFIDENTIAL>1</CONFIDENTIAL>
      <OFFCAMPUS>0</OFFCAMPUS>
    </EMPLOYEE_DATA>
    <STUDENT_DATA>
      <CAMPUS>0</CAMPUS>
      <ACADEMIC_LEVEL>41</ACADEMIC_LEVEL>
      <GEN_ACADEMIC_LEVEL>UG</GEN_ACADEMIC_LEVEL>
      <STATUS></STATUS>
      <LASTTERM>200701</LASTTERM>
      <NEXTTERM></NEXTTERM>
      <COLLEGE>08</COLLEGE>
      <MAJOR>BIOL</MAJOR>
      <DEGREE_SET>
        <DEGREE>
          <LEVEL>UG</LEVEL>
          <CODE>BS</CODE>
          <MAJOR>BIOL</MAJOR>
        </DEGREE>
        <DEGREE>
          <LEVEL>UG</LEVEL>
          <CODE>BA</CODE>
          <MAJOR>MATH</MAJOR>
        </DEGREE>
      </DEGREE_SET>
      <MAJOR_SET>
        <MAJOR>BIOL</MAJOR>
      </MAJOR_SET>
    </STUDENT_DATA>
    <NONVT_DATA>
      <EMAIL TYPE="ME">
        <EMAIL_ADDRESS>hizzy@vcom.edu</EMAIL_ADDRESS>
      </EMAIL>
    </NONVT_DATA>
  </PERSON>
</PERSONSET>
'

Example Response

POST /v1/replication/banner/consume HTTP/1.1
Content-Type: text/xml;charset=UTF-8
Content-Length: 3137
Host: api.middleware.vt.edu

<?xml version="1.0"?>
<PERSONSET>
  <PERSON>
    <BANNER_PIDM>7851451</BANNER_PIDM>
    <VT_IDNUM>916582945</VT_IDNUM>
    <UDC_IDENTIFIER>wynjITOTjVDLgDlMkkNoc6sZpkiRK1On</UDC_IDENTIFIER>
    <SSN_HASH>5j2s1isTALxcpVBXd6hJNUJyOMaYBByXNMR7DOB0irI=</SSN_HASH>
    <NAMESET>
      <BANNERNAME>
        <LASTNAME></LASTNAME>
        <FIRSTNAME></FIRSTNAME>
        <MIDDLENAME>IS</MIDDLENAME>
        <SUFFIX></SUFFIX>
      </BANNERNAME>
    </NAMESET>
    <BIRTHDATE>1990-11-30</BIRTHDATE>
    <CONFIDENTIAL_FLAG>1</CONFIDENTIAL_FLAG>
    <DECEASED_FLAG>0</DECEASED_FLAG>
    <GENDER>M</GENDER>
    <AFFILIATION_DATA>
      <AFFILIATION>VT-ALUM</AFFILIATION>
      <AFFILIATION>VT-ACTIVE-MEMBER</AFFILIATION>
      <AFFILIATION>VT-EMPLOYEE</AFFILIATION>
      <AFFILIATION>VT-EMPLOYEE-STATE</AFFILIATION>
      <AFFILIATION>VT-FACULTY</AFFILIATION>
      <AFFILIATION>VT-STUDENT</AFFILIATION>
    </AFFILIATION_DATA>
    <ADDRESS_SET>
      <ADDRESS TYPE="MA">
        <STREET1>1500 Maple St</STREET1>
        <STREET2>Tree #2</STREET2>
        <STREET3>Limb #1</STREET3>
        <CITY>War</CITY>
        <STATE_CODE>WV</STATE_CODE>
        <POSTALCODE>24892</POSTALCODE>
        <COUNTRY>USA</COUNTRY>
        <UNLISTED_FLAG>1</UNLISTED_FLAG>
        <MAILSTOP></MAILSTOP>
        <PHONESET>
          <PHONE TYPE="MA">
            <NUMBER>5405551212</NUMBER>
            <UNLISTED_FLAG>1</UNLISTED_FLAG>
          </PHONE>
        </PHONESET>
      </ADDRESS>
      <ADDRESS TYPE="OF">
        <STREET1>SETI-Middleware</STREET1>
        <STREET2>1700 Pratt Drive</STREET2>
        <STREET3></STREET3>
        <CITY>Blacksburg</CITY>
        <STATE_CODE>VA</STATE_CODE>
        <POSTALCODE>24060</POSTALCODE>
        <COUNTRY></COUNTRY>
        <UNLISTED_FLAG>0</UNLISTED_FLAG>
        <MAILSTOP>0479</MAILSTOP>
        <PHONESET>
          <PHONE TYPE="OF">
            <NUMBER>5402314357</NUMBER>
            <UNLISTED_FLAG>0</UNLISTED_FLAG>
          </PHONE>
        </PHONESET>
      </ADDRESS>
    </ADDRESS_SET>
    <EMPLOYEE_DATA>
      <EMPLOYEE_TYPE>3A</EMPLOYEE_TYPE>
      <JOB_TITLE>Trouble Maker</JOB_TITLE>
      <EMPLOYEE_STATUS>A</EMPLOYEE_STATUS>
      <HIREDATE>2010-01-01</HIREDATE>
      <TERMDATE></TERMDATE>
      <DEPT>066103</DEPT>
      <CONFIDENTIAL>1</CONFIDENTIAL>
      <OFFCAMPUS>0</OFFCAMPUS>
    </EMPLOYEE_DATA>
    <STUDENT_DATA>
      <CAMPUS>0</CAMPUS>
      <ACADEMIC_LEVEL>41</ACADEMIC_LEVEL>
      <GEN_ACADEMIC_LEVEL>UG</GEN_ACADEMIC_LEVEL>
      <STATUS></STATUS>
      <LASTTERM>200701</LASTTERM>
      <NEXTTERM></NEXTTERM>
      <COLLEGE>08</COLLEGE>
      <MAJOR>BIOL</MAJOR>
      <DEGREE_SET>
        <DEGREE>
          <LEVEL>UG</LEVEL>
          <CODE>BS</CODE>
          <MAJOR>BIOL</MAJOR>
        </DEGREE>
        <DEGREE>
          <LEVEL>UG</LEVEL>
          <CODE>BA</CODE>
          <MAJOR>MATH</MAJOR>
        </DEGREE>
      </DEGREE_SET>
      <MAJOR_SET>
        <MAJOR>BIOL</MAJOR>
      </MAJOR_SET>
    </STUDENT_DATA>
    <NONVT_DATA>
      <EMAIL TYPE="ME">
        <EMAIL_ADDRESS>hizzy@vcom.edu</EMAIL_ADDRESS>
      </EMAIL>
    </NONVT_DATA>
  </PERSON>
</PERSONSET>

Example Error Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 141

{
  "type" : "InsufficientAuthenticationException",
  "code" : 401,
  "message" : "Full authentication is required to access this resource"
}

Person Partially Updated

POST /v1/replication/banner/consume

Processes a Banner PERSONSET XML message.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/replication-banner ].

Example Request

$ curl 'https://api.middleware.vt.edu/v1/replication/banner/consume' -i -X POST \
    -H 'Content-Type: text/xml;charset=UTF-8' \
    -d '<?xml version="1.0"?>
<!--
  ~ See LICENSE for licensing and NOTICE for copyright.
  -->
<PERSONSET>
  <PERSON>
    <BANNER_PIDM>8675309</BANNER_PIDM>
    <VT_IDNUM>123</VT_IDNUM>
    <UDC_IDENTIFIER>abcde</UDC_IDENTIFIER>
    <NAMESET>
      <BANNERNAME>
        <LASTNAME>Bibblebush</LASTNAME>
        <FIRSTNAME>Bertha</FIRSTNAME>
        <MIDDLENAME>B</MIDDLENAME>
        <SUFFIX></SUFFIX>
      </BANNERNAME>
    </NAMESET>
    <BIRTHDATE>1990-11-30</BIRTHDATE>
    <CONFIDENTIAL_FLAG>1</CONFIDENTIAL_FLAG>
    <DECEASED_FLAG>0</DECEASED_FLAG>
    <GENDER>F</GENDER>
    <AFFILIATION_DATA>
      <AFFILIATION>VT-ACTIVE-MEMBER</AFFILIATION>
    </AFFILIATION_DATA>
    <ADDRESS_SET>
      <ADDRESS TYPE="MA">
        <STREET1>133 Worthington Way</STREET1>
        <STREET2>Apt 1A</STREET2>
        <!-- Next field exceeds constraint of 100 characters. -->
        <STREET3>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</STREET3>
        <CITY>Cambridge</CITY>
        <STATE_CODE>MA</STATE_CODE>
        <POSTALCODE>02138</POSTALCODE>
        <COUNTRY>USA</COUNTRY>
        <UNLISTED_FLAG>1</UNLISTED_FLAG>
        <MAILSTOP></MAILSTOP>
        <PHONESET>
          <PHONE TYPE="MA">
            <NUMBER>A12345678</NUMBER>
            <UNLISTED_FLAG>1</UNLISTED_FLAG>
          </PHONE>
        </PHONESET>
      </ADDRESS>
    </ADDRESS_SET>
  </PERSON>
</PERSONSET>
'

Example Response

POST /v1/replication/banner/consume HTTP/1.1
Content-Type: text/xml;charset=UTF-8
Content-Length: 1429
Host: api.middleware.vt.edu

<?xml version="1.0"?>
<!--
  ~ See LICENSE for licensing and NOTICE for copyright.
  -->
<PERSONSET>
  <PERSON>
    <BANNER_PIDM>8675309</BANNER_PIDM>
    <VT_IDNUM>123</VT_IDNUM>
    <UDC_IDENTIFIER>abcde</UDC_IDENTIFIER>
    <NAMESET>
      <BANNERNAME>
        <LASTNAME>Bibblebush</LASTNAME>
        <FIRSTNAME>Bertha</FIRSTNAME>
        <MIDDLENAME>B</MIDDLENAME>
        <SUFFIX></SUFFIX>
      </BANNERNAME>
    </NAMESET>
    <BIRTHDATE>1990-11-30</BIRTHDATE>
    <CONFIDENTIAL_FLAG>1</CONFIDENTIAL_FLAG>
    <DECEASED_FLAG>0</DECEASED_FLAG>
    <GENDER>F</GENDER>
    <AFFILIATION_DATA>
      <AFFILIATION>VT-ACTIVE-MEMBER</AFFILIATION>
    </AFFILIATION_DATA>
    <ADDRESS_SET>
      <ADDRESS TYPE="MA">
        <STREET1>133 Worthington Way</STREET1>
        <STREET2>Apt 1A</STREET2>
        <!-- Next field exceeds constraint of 100 characters. -->
        <STREET3>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</STREET3>
        <CITY>Cambridge</CITY>
        <STATE_CODE>MA</STATE_CODE>
        <POSTALCODE>02138</POSTALCODE>
        <COUNTRY>USA</COUNTRY>
        <UNLISTED_FLAG>1</UNLISTED_FLAG>
        <MAILSTOP></MAILSTOP>
        <PHONESET>
          <PHONE TYPE="MA">
            <NUMBER>A12345678</NUMBER>
            <UNLISTED_FLAG>1</UNLISTED_FLAG>
          </PHONE>
        </PHONESET>
      </ADDRESS>
    </ADDRESS_SET>
  </PERSON>
</PERSONSET>

Dev Team Resource API

Fetch

GET /v1/devteams/{name}

Fetches the developer team with the given name.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/devteams ].

Path Parameters

Table 8. /v1/devteams/{name}
Parameter Description

name

Name of developer team to fetch.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/devteams/the-a-team' -i -X GET

Example Response

GET /v1/devteams/the-a-team HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 110

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Group with ID developer.someteam not found"
}

Query

GET /v1/devteams

Query for developer teams that the current principal is authorized to view.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/devteams ].

Query Parameters

Parameter Optional Description

name

true

Optional name expression to limit results to developer teams matching the given name. Supports wildcards, e.g. dbaa*.

member

true

Optional member uid used to select teams containing the given member.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/devteams?name=the-*&member=20011610' -i -X GET

Example Response

GET /v1/devteams?name=the-*&member=20011610 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Create

POST /v1/devteams

Creates a new developer team.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/devteams ].

Form Parameters

Parameter Optional Description

name

false

Developer team name.

member

false

One or more names of groups to nest inside the developer team group.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/devteams' -i -X POST \
    -d 'name=the-b-team&member=member1&member=member2'

Example Response

POST /v1/devteams HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 45

name=the-b-team&member=member1&member=member2

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Entitlement Resource API

Fetch

GET /v1/entitlements/{id}

Fetches the entitlement with the given unique identifier.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Path Parameters

Table 9. /v1/entitlements/{id}
Parameter Description

id

ID of entitlement.

Query Parameters

Parameter Optional Description

with

true

Zero or more optional sections of fields to include in fetched resource.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/entitlements/1977?with=viewers' -i -X GET

Example Response

GET /v1/entitlements/1977?with=viewers HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Grant with ID 19591000 not found"
}

Query

GET /v1/entitlements

Fetches a collection of entitlement resources based on query terms.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Query Parameters

Parameter Optional Description

person

true

User bearing the entitlement

service

true

Service bearing the entitlement

group

true

Group bearing the entitlement

owner

true

Principal who is the owner(manager) of the entitlement

name

true

Name of the entitlement

sponsor

true

Sponsor of the entitlement

viewer

true

Subject in viewer role on the entitlement

with

true

Zero or more optional sections of fields to include in fetched resources.

page

true

Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided.

size

true

Size of the page you want to retrieve. Must be greater than 0.

sort

true

How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/entitlements?name=ed%2Ftest%2Fent%2F*&owner=middleware-test' -i -X GET

Example Response

GET /v1/entitlements?name=ed%2Ftest%2Fent%2F*&owner=middleware-test HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Create

POST /v2/entitlements

Creates an entitlement.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Form Parameters

Parameter Optional Description

resource

false

Resource of the entitlement.

scope

true

Scope of the entitlement.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/entitlements' -i -X POST \
    -d 'resource=test%2Fresource'

Example Response

POST /v2/entitlements HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 24

resource=test%2Fresource

Example Error Response

HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 129

{
  "type" : "FoundException",
  "code" : 409,
  "message" : "Entitlement with ID middleware-test:test/resource already exists"
}

Delete

DELETE /v2/entitlements/{id}

Deletes the given entitlement.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Path Parameters

Table 10. /v2/entitlements/{id}
Parameter Description

id

A unique identifier for the entitlement.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/entitlements/20015164' -i -X DELETE

Example Response

DELETE /v2/entitlements/20015164 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 101

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Entitlement with ID 123 not found"
}

Create And Grant

POST /v1/entitlements

Creates an entitlement and grants it to a subject identified by either the user or service parameters (one or the other is required).

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Form Parameters

Parameter Optional Description

name

false

Entitlement resource URI.

scope

true

Scope of the entitlement.

person

true

User to whom to grant the entitlement.

service

true

Service to which to grant the entitlement.

sponsor

true

User who initiated the granting of the entitlement. If not specified, the principal that invokes the operation is the grantor.

expiration

true

Expiration date after which the granted entitlement is automatically revoked by the system.

viewer

true

Zero or more service viewers of the entitlement.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/entitlements' -i -X POST \
    -d 'name=test%2Fent%2F5&person=800001&expiration=1893456000'

Example Response

POST /v1/entitlements HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 55

name=test%2Fent%2F5&person=800001&expiration=1893456000

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 94

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "User with ID 123 not found"
}

Revoke

DELETE /v1/entitlements/{id}

Revokes the given grant (equivalent of EDv4 entitlement).

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Path Parameters

Table 11. /v1/entitlements/{id}
Parameter Description

id

ID of grant.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/entitlements/2041' -i -X DELETE

Example Response

DELETE /v1/entitlements/2041 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 97

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Grant with ID 12345 not found"
}

Add Viewers

POST /v1/entitlements/{uid}/viewers

Adds the given service viewers to an existing entitlement.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Path Parameters

Table 12. /v1/entitlements/{uid}/viewers
Parameter Description

uid

ID of grant.

Form Parameters

Parameter Optional Description

expiration

true

Expiration date of viewer role.

viewer

false

Username of services to add as viewers of the entitlement.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/entitlements/1962/viewers' -i -X POST \
    -d 'viewer=svc-v1&viewer=svc-v2'

Example Response

POST /v1/entitlements/1962/viewers HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 27

viewer=svc-v1&viewer=svc-v2

Example Error Response

HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104

{
  "type" : "FoundException",
  "code" : 409,
  "message" : "Subject with ID 20015232 already exists"
}

Remove Viewer

DELETE /v1/entitlements/{uid}/viewers/{id}

Removes the given service viewer from an existing entitlement.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Path Parameters

Table 13. /v1/entitlements/{uid}/viewers/{id}
Parameter Description

uid

ID of grant.

id

Username of service viewer to remove.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/entitlements/2028/viewers/svc-v2' -i -X DELETE

Example Response

DELETE /v1/entitlements/2028/viewers/svc-v2 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 102

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Subject with ID 20014974 not found"
}

Update Relation

PATCH /v1/entitlements/{uid}/{role}/{id}

Updates the entitlement relation given a JSON patch.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/entitlements ].

Path Parameters

Table 14. /v1/entitlements/{uid}/{role}/{id}
Parameter Description

uid

ID of grant.

role

Entitlement role. At present, only viewers are supported.

id

Username of service to update.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/entitlements/1957/viewers/svc-v1' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/expiration","value":31536000}]'

Example Response

PATCH /v1/entitlements/1957/viewers/svc-v1 HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 56
Host: api.middleware.vt.edu

[{"op":"replace","path":"/expiration","value":31536000}]

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Service with ID svc-v1 not found"
}

Group Resource API

Fetch

GET /v1/groups/{uugid}

Fetches the group with the given unique name.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 15. /v1/groups/{uugid}
Parameter Description

uugid

Name of group to fetch.

Query Parameters

Parameter Optional Description

with

true

Zero or more optional sections of fields to include in fetched group resource.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/middleware.dvlp?with=members&with=membership&with=replication&with=suppression' -i -X GET

Example Response

GET /v1/groups/middleware.dvlp?with=members&with=membership&with=replication&with=suppression HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 107

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Group with ID middleware.dvlp not found"
}

Fetch Relation

GET /v1/groups/{uugid}/{role}/{id}

Fetches a relation on a group for a specific subject.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 16. /v1/groups/{uugid}/{role}/{id}
Parameter Description

uugid

Name of group to search.

role

Role the subject belongs to on the group.

Must be one of: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ]

id

Unique identifier of the subject to fetch.

Query Parameters

Parameter Optional Description

kind

true

The kind of subject.

Must be one of: [ GROUP, PERSON, SERVICE ]

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/group.a/members/middleware' -i -X GET

Example Response

GET /v1/groups/group.a/members/middleware HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 168

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'unknown'. Valid types: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ]"
}

Query

GET /v1/groups?uugid=middleware*

Fetches a collection of group resources based on query terms.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Query Parameters

Parameter Optional Description

uugid

true

Unique identifier

crafter

true

Created date after

crbefore

true

Created date before

exafter

true

Expiration date after

exbefore

true

Expiration date before

member

true

Group member name (may be an account username identifying a person or service or group name)

child

true

Nested group name (use this parameter if you are seaching for child groups explicitly)

administrator

true

Subject in administrator role

contact

true

Subject in contact role (deprecated)

manager

true

Subject in manager role

viewer

true

Subject in viewer role

with

true

Zero or more optional sections of fields to include in fetched group resources.

page

true

Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided.

size

true

Size of the page you want to retrieve. Must be greater than 0.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups?uugid=middleware*' -i -X GET

Example Response

GET /v1/groups?uugid=middleware* HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Create

POST /v1/groups

Creates a new group resource.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Form Parameters

Parameter Optional Description

uugid

false

Unique group name of group to create.

contact

false

One or more group contacts.

administrator

false

One or more group administrators.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups' -i -X POST \
    -d 'uugid=test.group-1&administrator=alice&administrator=bob&contact=bob'

Example Response

POST /v1/groups HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 68

uugid=test.group-1&administrator=alice&administrator=bob&contact=bob

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 143

{
  "type" : "PolicyException",
  "code" : 400,
  "message" : "middleware-test must be an administrator of a parent group to create test.aaa"
}

Add Relation

POST /v1/groups/{uugid}/{role}

Adds a member to a group role/relation.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 17. /v1/groups/{uugid}/{role}
Parameter Description

uugid

ID of group to update.

role

Role to add members to.

Must be one of: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ]

Form Parameters

Parameter Optional Description

kind

false

Kind of member to add.

Must be one of: [ GROUP, PERSON, SERVICE ]

id

false

Username or UID of subject to add. Only username is allowed for Admin and Contact.

expiration

true

Expiration date.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/test.group/administrators' -i -X POST \
    -d 'id=connie&kind=person'

Example Response

POST /v1/groups/test.group/administrators HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 21

id=connie&kind=person

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 143

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'invalid-kind'. Valid types: [ GROUP, PERSON, SERVICE ]"
}

Remove Relation

DELETE /v1/groups/{uugid}/{role}/{id}

Removes a member from a group role/relation.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 18. /v1/groups/{uugid}/{role}/{id}
Parameter Description

uugid

ID of group to update.

role

Role to remove members from.

Must be one of: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ]

id

Username or UID of subject to remove from role.

Query Parameters

Parameter Optional Description

kind

true

Kind of member to remove.

Must be one of: [ GROUP, PERSON, SERVICE ]

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/test.group/members/pidlike?kind=person' -i -X DELETE \
    -H 'Content-Type: application/x-www-form-urlencoded'

Example Response

DELETE /v1/groups/test.group/members/pidlike?kind=person HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/groups/test.update/contacts/alice
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Update Relation

PATCH /v1/groups/{uugid}/{role}/{id}

Updates the group relation given a JSON patch.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 19. /v1/groups/{uugid}/{role}/{id}
Parameter Description

uugid

Group unique name.

role

Group role.

Must be one of: [ ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS ]

id

Id of group relation subject to update.

Query Parameters

Parameter Optional Description

kind

true

Kind of subject.

Must be one of: [ GROUP, PERSON, SERVICE ]

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/test.update/managers/middleware-test?kind=service' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json;charset=utf-8' \
    -d '[{"op":"replace","path":"/expirationDate","value":1762033198}]'

Example Response

PATCH /v1/groups/test.update/managers/middleware-test?kind=service HTTP/1.1
Content-Type: application/json-patch+json;charset=utf-8
Content-Length: 62
Host: api.middleware.vt.edu

[{"op":"replace","path":"/expirationDate","value":1762033198}]

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 291

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Failed applying patch: Group does not support expiration in ADMIN role\n at [Source: UNKNOWN; byte offset: #UNKNOWN] (through reference chain: edu.vt.middleware.ed.ws.rest.model.JsonGroupRelative[\"expirationDate\"])"
}

Update

PATCH /v1/groups/{uugid}

Updates the group given a JSON patch.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 20. /v1/groups/{uugid}
Parameter Description

uugid

Group unique name.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/test.group.arsenic' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/suppressDisplay","value":true},{"op":"replace","path":"/expirationDate","value":1762033171},{"op":"replace","path":"/displayName","value":"a common n-type dopant in semiconductor electronic devices"}]'

Example Response

PATCH /v1/groups/test.group.arsenic HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 226
Host: api.middleware.vt.edu

[{"op":"replace","path":"/suppressDisplay","value":true},{"op":"replace","path":"/expirationDate","value":1762033171},{"op":"replace","path":"/displayName","value":"a common n-type dopant in semiconductor electronic devices"}]

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 134

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Failed applying patch: no such path in target JSON document"
}

Delete

DELETE /v1/groups/{uugid}

Deletes a group resource.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 21. /v1/groups/{uugid}
Parameter Description

uugid

ID of group to delete.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/test.middle.leaf' -i -X DELETE

Example Response

DELETE /v1/groups/test.middle.leaf HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Group with ID does-not-exist not found"
}

Batch Add Relations

POST /v1/groups/{uugid}/relations

Batch adds the given relations.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 22. /v1/groups/{uugid}/relations
Parameter Description

uugid

Group to modify.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/test.batch.two/relations' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '[{"role":"members","kind":"person","id":"alpha"},{"role":"members","kind":"person","id":"beta"},{"role":"members","kind":"person","id":"gamma"},{"role":"members","kind":"person","id":"gamma"},{"role":"members","kind":"service","id":"delta"},{"role":"members","kind":"service","id":"notfound1"},{"role":"members","kind":"service","id":"notfound2"},{"role":"administrators","kind":"person","id":"alpha"},{"role":"administrators","kind":"service","id":"delta"},{"role":"administrators","kind":"service","id":"notfound2"},{"role":"viewers","kind":"service","id":"epsilon"},{"role":"managers","kind":"service","id":"foo"},{"role":"managers","kind":"service","id":"notfound2"}]'

Example Response

POST /v1/groups/test.batch.two/relations HTTP/1.1
Content-Type: application/json
Content-Length: 671
Host: api.middleware.vt.edu

[{"role":"members","kind":"person","id":"alpha"},{"role":"members","kind":"person","id":"beta"},{"role":"members","kind":"person","id":"gamma"},{"role":"members","kind":"person","id":"gamma"},{"role":"members","kind":"service","id":"delta"},{"role":"members","kind":"service","id":"notfound1"},{"role":"members","kind":"service","id":"notfound2"},{"role":"administrators","kind":"person","id":"alpha"},{"role":"administrators","kind":"service","id":"delta"},{"role":"administrators","kind":"service","id":"notfound2"},{"role":"viewers","kind":"service","id":"epsilon"},{"role":"managers","kind":"service","id":"foo"},{"role":"managers","kind":"service","id":"notfound2"}]

Batch Remove Relations

DELETE /v1/groups/{uugid}/relations

Batch removes the given relations.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/groups ].

Path Parameters

Table 23. /v1/groups/{uugid}/relations
Parameter Description

uugid

Group to modify.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/groups/test.batch.three/relations' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -d '[{"role":"members","kind":"person","id":"anna"},{"role":"members","kind":"person","id":"beth"},{"role":"members","kind":"person","id":"ginny"},{"role":"members","kind":"person","id":"ginny"},{"role":"members","kind":"service","id":"dave"},{"role":"administrators","kind":"person","id":"anna"},{"role":"administrators","kind":"service","id":"dave"},{"role":"viewers","kind":"service","id":"ernie"},{"role":"viewers","kind":"service","id":"notfound1"},{"role":"viewers","kind":"service","id":"notfound2"},{"role":"managers","kind":"service","id":"foo"},{"role":"managers","kind":"service","id":"notfound2"}]'

Example Response

DELETE /v1/groups/test.batch.three/relations HTTP/1.1
Content-Type: application/json
Content-Length: 605
Host: api.middleware.vt.edu

[{"role":"members","kind":"person","id":"anna"},{"role":"members","kind":"person","id":"beth"},{"role":"members","kind":"person","id":"ginny"},{"role":"members","kind":"person","id":"ginny"},{"role":"members","kind":"service","id":"dave"},{"role":"administrators","kind":"person","id":"anna"},{"role":"administrators","kind":"service","id":"dave"},{"role":"viewers","kind":"service","id":"ernie"},{"role":"viewers","kind":"service","id":"notfound1"},{"role":"viewers","kind":"service","id":"notfound2"},{"role":"managers","kind":"service","id":"foo"},{"role":"managers","kind":"service","id":"notfound2"}]

ID Proof Resource API

Grade

POST /v1/persons/{uid}/questions/{qid}/grade

Grades a single answer as a pass/fail.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/persons-challenge ].

Path Parameters

Table 24. /v1/persons/{uid}/questions/{qid}/grade
Parameter Description

uid

UID of user whose challenge question is being graded.

qid

Question id of the question being graded.

Form Parameters

Parameter Optional Description

answer

false

To be graded.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/persons/20013907/questions/fname/grade' -i -X POST \
    -d 'answer=Alice'

Example Response

POST /v1/persons/20013907/questions/fname/grade HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 12

answer=Alice

Example Error Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 20

{
  "pass" : false
}

Questions

GET /v1/persons/{uid}/questions

Returns a list of questions based on affiliations. The ordered/prioritized Map of question types is iterated and the first matching affiliation of the person is used to populate the questions.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/persons-challenge ].

Path Parameters

Table 25. /v1/persons/{uid}/questions
Parameter Description

uid

UID of user whose identity challenge questions will be returned.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/persons/20013923/questions' -i -X GET

Example Response

GET /v1/persons/20013923/questions HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Mailbox Resource API

Fetch

GET /v2/mailboxes/{address}

Fetches the mailbox with the given unique address identifier - an Email.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].

Path Parameters

Table 26. /v2/mailboxes/{address}
Parameter Description

address

Address of mailbox to fetch.

Query Parameters

Parameter Optional Description

with

true

Zero or more optional sections of fields to include in fetched mailbox resource.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu?with=addresses&with=state' -i -X GET

Example Response

GET /v2/mailboxes/alice@vt.edu?with=addresses&with=state HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Mailbox with ID alice@vt.edu not found"
}

Query

GET /v2/mailboxes?any=match*&type=forwarding&with=state

Fetches a collection of mailbox resources based on query terms.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].

Query Parameters

Parameter Optional Description

address

true

Primary (MAILBOX) address of the mailbox

alias

true

ALIAS address of the mailbox

forward

true

FORWARD address of the mailbox

any

true

Any type of address of the mailbox (MAILBOX, ALIAS, FORWARD)

username

true

Username of the mailbox owner

type

true

Type of the mailbox

state

true

State of the mailbox

uid

true

UID of the mailbox owner

exafter

true

Mailbox expiring after the given date

exbefore

true

Mailbox expiring before the given date

with

true

Zero or more optional sections of fields to include in fetched mailbox resources.

page

true

Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided.

size

true

Size of the page you want to retrieve. Must be greater than 0.

sort

true

How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/mailboxes?any=match*&type=forwarding&with=state' -i -X GET

Example Response

GET /v2/mailboxes?any=match*&type=forwarding&with=state HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Add Alias

POST /v2/mailboxes/{address}/aliases

Adds an email alias to a mailbox resource.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].

Path Parameters

Table 27. /v2/mailboxes/{address}/aliases
Parameter Description

address

Unique string identifier of the mailbox to update, which is its primary address.

Form Parameters

Parameter Optional Description

alias

false

Email address to add as an alias of the mailbox.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu/aliases' -i -X POST \
    -d 'alias=alias%40vt.edu'

Example Response

POST /v2/mailboxes/alice@vt.edu/aliases HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 20

alias=alias%40vt.edu

Example Error Response

HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106

{
  "type" : "FoundException",
  "code" : 409,
  "message" : "Email with ID alias@vt.edu already exists"
}

Remove Alias

DELETE /v2/mailboxes/{address}/aliases/{alias}

Removes an email alias from a mailbox resource.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].

Path Parameters

Table 28. /v2/mailboxes/{address}/aliases/{alias}
Parameter Description

address

Unique string identifier of the mailbox to update, which is its primary address.

alias

Email address to remove from the aliases of the mailbox.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu/aliases/alias@vt.edu' -i -X DELETE

Example Response

DELETE /v2/mailboxes/alice@vt.edu/aliases/alias@vt.edu HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Email with ID alias@vt.edu not found"
}

Add Forward

POST /v2/mailboxes/{address}/forwards

Adds a forward to a mailbox resource.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].

Path Parameters

Table 29. /v2/mailboxes/{address}/forwards
Parameter Description

address

Unique string identifier of the mailbox to update, which is its primary address.

Form Parameters

Parameter Optional Description

forward

false

Email address to add as a forward to mailbox.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu/forwards' -i -X POST \
    -d 'forward=forward%40vt.edu'

Example Response

POST /v2/mailboxes/alice@vt.edu/forwards HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 24

forward=forward%40vt.edu

Example Error Response

HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 108

{
  "type" : "FoundException",
  "code" : 409,
  "message" : "Email with ID forward@vt.edu already exists"
}

Remove Forward

DELETE /v2/mailboxes/{address}/forwards/{forward}

Removes a forward from a mailbox resource.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].

Path Parameters

Table 30. /v2/mailboxes/{address}/forwards/{forward}
Parameter Description

address

Unique string identifier of the mailbox to update, which is its primary address.

forward

Email address to remove from the forwards of the mailbox.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu/forwards/forward@vt.edu' -i -X DELETE

Example Response

DELETE /v2/mailboxes/alice@vt.edu/forwards/forward@vt.edu HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Email with ID forward@vt.edu not found"
}

Update Mail Preferred Address

PATCH /v2/mailboxes/{address}

Updates an existing mailbox.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].

Path Parameters

Table 31. /v2/mailboxes/{address}
Parameter Description

address

Unique string identifier of the mailbox to update, which is its primary address.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/mailboxes/primary@vt.edu' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/preferredAddress","value":"preferred-alias@vt.edu"}]'

Example Response

PATCH /v2/mailboxes/primary@vt.edu HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 78
Host: api.middleware.vt.edu

[{"op":"replace","path":"/preferredAddress","value":"preferred-alias@vt.edu"}]

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Update Mail Route

PATCH /v2/mailboxes/{address}

Updates an existing mailbox route.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/mailboxes ].

Path Parameters

Table 32. /v2/mailboxes/{address}
Parameter Description

address

Unique string identifier of the mailbox to update, which is its primary address.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/mailboxes/alice@vt.edu' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/routeType","value":"exchange"}]'

Example Response

PATCH /v2/mailboxes/alice@vt.edu HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 57
Host: api.middleware.vt.edu

[{"op":"replace","path":"/routeType","value":"exchange"}]

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Mailbox with ID alice@vt.edu not found"
}

Namespace Resource API

Is Available

GET /v2/namespaces/{namespace}/values/{value}

Checks if the given namespace:value combination is available.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/namespaces ].

Path Parameters

Table 33. /v2/namespaces/{namespace}/values/{value}
Parameter Description

namespace

The namespace to check.

Must be one of: [ COALITION, EMAIL, GROUP, OAUTH2, PAIRWISE, PIDM, RESERVED, SAML, SSN, SUBJECT, UDCID, USERNAME, VTID ]

value

The namespace value.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/namespaces/username/values/iap.username' -i -X GET

Example Response

GET /v2/namespaces/username/values/iap.username HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
Content-Length: 21
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

{
  "value" : false
}

Reserve

POST /v2/namespaces/reserved

Reserves the given name in the Enterprise Directory such that it is subsequently ineligible for allocation in any namespace in the Enterprise Directory.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/namespaces ].

Form Parameters

Parameter Optional Description

value

false

Namespace value to reserve.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/namespaces/reserved' -i -X POST \
    -d 'value=rp.username'

Example Response

POST /v2/namespaces/reserved HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 17

value=rp.username

Example Error Response

HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 108

{
  "type" : "FoundException",
  "code" : 409,
  "message" : "Reserve with ID rnf.username already exists"
}

Unreserve

DELETE /v2/namespaces/reserved/{value}

Removes the given reserved name in the Enterprise Directory such that it is subsequently eligible for allocation.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/namespaces ].

Path Parameters

Table 34. /v2/namespaces/reserved/{value}
Parameter Description

value

Namespace value for which to remove reservation.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/namespaces/reserved/urp.username' -i -X DELETE

Example Response

DELETE /v2/namespaces/reserved/urp.username HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 108

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Reserve with ID urnnf.username not found"
}

Password Complexity API

Validate

POST /v1/password/validate

Validates a password.

Authorization

HTTP Auth is not required.

Form Parameters

Parameter Optional Description

userid

false

Userid associated with the password.

password

false

To check complexity.

type

true

Of the userid.

Must be one of: [ AD, BANNER, ORACLE, PID ]

with

true

To include in the response.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/password/validate' -i -X POST \
    -d 'userid=dfisher&password=testingpasss&with=messages&with=details'

Example Response

POST /v1/password/validate HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 63

userid=dfisher&password=testingpasss&with=messages&with=details

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 103

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Illegal sections: [badinput]"
}

Rules

GET /v1/password/rules?type=pid

Returns the password validation rules.

Authorization

HTTP Auth is not required.

Query Parameters

Parameter Optional Description

type

true

Of the desired rule set.

Must be one of: [ AD, BANNER, ORACLE, PID ]

Example Request

$ curl 'https://api.middleware.vt.edu/v1/password/rules?type=pid' -i -X GET

Example Response

GET /v1/password/rules?type=pid HTTP/1.1
Host: api.middleware.vt.edu

Person LDAP Search API

Fuzzy

GET /v1/persons/ldap/fuzzysearch?query=stone&attr=givenName

Performs a fuzzy LDAP search.

Authorization

HTTP Auth is not required.

Query Parameters

Parameter Optional Description

query

false

To search against the template.

attr

true

Attributes to return.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/persons/ldap/fuzzysearch?query=stone&attr=givenName' -i -X GET

Example Response

GET /v1/persons/ldap/fuzzysearch?query=stone&attr=givenName HTTP/1.1
Host: api.middleware.vt.edu

Search

GET /v1/persons/ldap/search?filter=(givenName=b*)&attr=sn

Performs an LDAP search.

Authorization

HTTP Auth is not required.

Query Parameters

Parameter Optional Description

filter

false

To execute against the ldap.

attr

true

Attributes to return.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/persons/ldap/search?filter=(givenName%3Db*)&attr=sn' -i -X GET

Example Response

GET /v1/persons/ldap/search?filter=(givenName%3Db*)&attr=sn HTTP/1.1
Host: api.middleware.vt.edu

Person Resource API

Delete

DELETE /v2/persons/{uid}

Deletes the Person.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/persons ].

Path Parameters

Table 35. /v2/persons/{uid}
Parameter Description

uid

UID of person.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/persons/20014845' -i -X DELETE

Example Response

DELETE /v2/persons/20014845 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 164

{
  "type" : "BlockingDataException",
  "code" : 400,
  "message" : "The delete on Donald Duck was blocked by existence of [User(ID=20014854), User(ID=20014856)]"
}

Service Resource API

Create

POST /v1/services

Creates a new service using an authenticated Service principal that is authorized to create services. Services are permitted to invoke this endpoint by granting the following middleware entitlements: - ed/rest/services - ed/manage/service-manager#create-service.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Form Parameters

Parameter Optional Description

uusid

false

Service unique identifier; follows requirements for ED account usernames.

expires

false

Requested service expiration date expressed as a Unix epoch (int) or date string in ISO 8601 format.

administrator

false

List of one or more service administrators identified by username (or group name if a group).

contact

true

List of zero or more service contacts identified by username (or group name if a group).

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services' -i -X POST \
    -d 'uusid=waw&expires=1762033060&administrator=andy&contact=candace'

Example Response

POST /v1/services HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 63

uusid=waw&expires=1762033060&administrator=andy&contact=candace

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Account with ID nobody not found"
}

Fetch

GET /v1/services/{uusid}

Fetches a service resource that is uniquely identified by the given uusid.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 36. /v1/services/{uusid}
Parameter Description

uusid

Service unique string identifier.

Query Parameters

Parameter Optional Description

with

true

Zero or more optional sections of fields to include in fetched service resource.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/iota?with=all' -i -X GET

Example Response

GET /v1/services/iota?with=all HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Query

GET /v1/services

Fetches a collection of service resources based on query terms.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Query Parameters

Parameter Optional Description

client_id

true

OAuth2 client identifier

crafter

true

Created date after

crbefore

true

Created date before

devteam

true

Developer team name

entity_id

true

SAML entity ID

readable_attribute

true

Attribute service can access

uusid

true

Unique identifier

administrator

true

Subject in administrator role

contact

true

Subject in contact role (deprecated)

manager

true

Subject in manager role

with

true

Zero or more optional sections of fields to include in fetched service resources.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services?client_id=a97fb5b1-ae12-1008-9c62-000edf235d76' -i -X GET

Example Response

GET /v1/services?client_id=a97fb5b1-ae12-1008-9c62-000edf235d76 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Add Relation

POST /v1/services/{uusid}/{role}

Adds a member to a service role/relation.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 37. /v1/services/{uusid}/{role}
Parameter Description

uusid

ID of service to update.

role

Role to add members to.

Must be one of: [ ADMINISTRATORS, CONTACTS, VIEWERS ]

Form Parameters

Parameter Optional Description

kind

false

Kind of member to add.

Must be one of: [ GROUP, PERSON, SERVICE ]

id

false

Unique identifier of member to add.

expiration

true

Requested service expiration date expressed as a Unix epoch (int) or date string in ISO 8601 format.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/alpha/administrators' -i -X POST \
    -d 'id=alice&kind=person&expiration=2024-12-01T17%3A37%3A57.169750228-05%3A00'

Example Response

POST /v1/services/alpha/administrators HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 73

id=alice&kind=person&expiration=2024-12-01T17%3A37%3A57.169750228-05%3A00

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Remove Relation

DELETE /v1/services/{uusid}/{role}/{id}

Removes a member from a service role/relation.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 38. /v1/services/{uusid}/{role}/{id}
Parameter Description

uusid

ID of service to update.

role

Role to remove member from.

Must be one of: [ ADMINISTRATORS, CONTACTS, VIEWERS ]

id

ID of member to remove from role.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/alpha/administrators/test.middleware-group' -i -X DELETE

Example Response

DELETE /v1/services/alpha/administrators/test.middleware-group HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Shelve

POST /v2/services/{uusid}/shelve

Shelves a service account. Sets the primary account state to SHELVED.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 39. /v2/services/{uusid}/shelve
Parameter Description

uusid

Service account to shelve.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/services/middleware-shelve/shelve' -i -X POST

Example Response

POST /v2/services/middleware-shelve/shelve HTTP/1.1
Host: api.middleware.vt.edu
Content-Type: application/x-www-form-urlencoded

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Add Viewable Person Attributes

POST /v1/services/{uusid}/viewable-person-attributes

Adds one or more viewable person attributes to a service.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 40. /v1/services/{uusid}/viewable-person-attributes
Parameter Description

uusid

ID of service to update.

Form Parameters

Parameter Optional Description

attribute

false

List of person attributes, one for each occurrence of attribute in the entity body.

Must be one of: [ academicLevel, accountCheckupDate, accountCreationDate, accountExpirationDate, accountShelveDate, accountSponsor, accountState, accountTransition, authId, bannerName, bannerPIDM, c, campus, channel, city, classLevel, classLevelCode, cn, coalitionID, college, creationDate, dateOfBirth, deceasedFlag, degreeType, department, departmentNumber, displayName, eduPersonAffiliation, eduPersonAssurance, eduPersonEntitlement, eduPersonNickname, eduPersonOrcid, eduPersonOrgDN, eduPersonOrgUnitDN, eduPersonPrimaryAffiliation, eduPersonPrimaryOrgUnitDN, eduPersonPrincipalName, eduPersonScopedAffiliation, eduPersonTargetedID, eduPersonUniqueId, employeeConfidential, employeeOffCampus, facsimileTelephoneNumber, gender, gidNumber, givenName, googleMailbox, groupMembership, groupMembershipUugid, guestId, hokiesPassword, homeDirectory, homeFax, homeMobile, homePager, homePhone, homePostalAddress, instantMessagingID, isMemberOf, l, labeledURI, lastEnrollmentTerm, lastEnrollmentTermCode, localFax, localMobile, localPager, localPhone, localPostalAddress, mail, mailAccount, mailAccountState, mailAlias, mailAuxiliaryAccount, mailDisplayAddress, mailExternalAddress, mailForwardingAddress, mailPreferredAddress, mailStop, major, majorCode, middleName, mobile, modificationDate, networkPassword, nextEnrollmentTerm, nextEnrollmentTermCode, objectClass, ou, pager, pairwiseId, passwordChangeDate, passwordExpirationDate, passwordState, personType, postOfficeBox, postalAddress, postalCode, preferredFirstName, preferredLastName, preferredMiddleName, preferredSuffix, publicDirectoryAttributes, selfPhone, selfPostalAddress, showInPublicDirectory, sn, st, street, street1, street2, studentConfidential, studentLevelCode, subjectId, suppressAll, suppressDisplay, suppressEmployeeDisplay, suppressedAttribute, targetedMembership, telephoneNumber, title, udcIdentifier, uid, uidNumber, undergraduateLevel, userCertificate, userPassword, userSMIMECertificate, username, uupid, virginiaTechAffiliation, virginiaTechID ]

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/delta/viewable-person-attributes' -i -X POST \
    -d 'attribute=displayName&attribute=mailPreferredAddress'

Example Response

POST /v1/services/delta/viewable-person-attributes HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 52

attribute=displayName&attribute=mailPreferredAddress

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 148

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "No enum constant edu.vt.middleware.ed.model.db.LdapPersonAttributeDef.ALL"
}

Remove Viewable Person Attribute

DELETE /v1/services/{uusid}/viewable-person-attributes/{attribute}

Removes the given viewable person attribute from a service.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 41. /v1/services/{uusid}/viewable-person-attributes/{attribute}
Parameter Description

uusid

ID of service to update.

attribute

Viewable person attribute.

Must be one of: [ academicLevel, accountCheckupDate, accountCreationDate, accountExpirationDate, accountShelveDate, accountSponsor, accountState, accountTransition, authId, bannerName, bannerPIDM, c, campus, channel, city, classLevel, classLevelCode, cn, coalitionID, college, creationDate, dateOfBirth, deceasedFlag, degreeType, department, departmentNumber, displayName, eduPersonAffiliation, eduPersonAssurance, eduPersonEntitlement, eduPersonNickname, eduPersonOrcid, eduPersonOrgDN, eduPersonOrgUnitDN, eduPersonPrimaryAffiliation, eduPersonPrimaryOrgUnitDN, eduPersonPrincipalName, eduPersonScopedAffiliation, eduPersonTargetedID, eduPersonUniqueId, employeeConfidential, employeeOffCampus, facsimileTelephoneNumber, gender, gidNumber, givenName, googleMailbox, groupMembership, groupMembershipUugid, guestId, hokiesPassword, homeDirectory, homeFax, homeMobile, homePager, homePhone, homePostalAddress, instantMessagingID, isMemberOf, l, labeledURI, lastEnrollmentTerm, lastEnrollmentTermCode, localFax, localMobile, localPager, localPhone, localPostalAddress, mail, mailAccount, mailAccountState, mailAlias, mailAuxiliaryAccount, mailDisplayAddress, mailExternalAddress, mailForwardingAddress, mailPreferredAddress, mailStop, major, majorCode, middleName, mobile, modificationDate, networkPassword, nextEnrollmentTerm, nextEnrollmentTermCode, objectClass, ou, pager, pairwiseId, passwordChangeDate, passwordExpirationDate, passwordState, personType, postOfficeBox, postalAddress, postalCode, preferredFirstName, preferredLastName, preferredMiddleName, preferredSuffix, publicDirectoryAttributes, selfPhone, selfPostalAddress, showInPublicDirectory, sn, st, street, street1, street2, studentConfidential, studentLevelCode, subjectId, suppressAll, suppressDisplay, suppressEmployeeDisplay, suppressedAttribute, targetedMembership, telephoneNumber, title, udcIdentifier, uid, uidNumber, undergraduateLevel, userCertificate, userPassword, userSMIMECertificate, username, uupid, virginiaTechAffiliation, virginiaTechID ]

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/foxtrot/viewable-person-attributes/sn' -i -X DELETE

Example Response

DELETE /v1/services/foxtrot/viewable-person-attributes/sn HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Add Endpoint

POST /v1/services/{uusid}/endpoints

Adds a service endpoint.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 42. /v1/services/{uusid}/endpoints
Parameter Description

uusid

ID of service to update.

Form Parameters

Parameter Optional Description

protocol

false

Endpoint communication protocol.

Must be one of: [ CAS, HTTP, LDAP, OAUTH2, OIDC, SAML2 ]

location

false

Endpoint location URI.

binding

true

Binding; required when protocol is SAML2.

kind

true

Optional protocol-specific kind, e.g. "AssertionConsumerService" for a SAML endpoint.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/heh/endpoints' -i -X POST \
    -d 'protocol=OAUTH2&location=https%3A%2F%2Fexample.org%2Foauth2_callback'

Example Response

POST /v1/services/heh/endpoints HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 68

protocol=OAUTH2&location=https%3A%2F%2Fexample.org%2Foauth2_callback

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 177

{
  "type" : "MissingServletRequestParameterException",
  "code" : 400,
  "message" : "Required request parameter 'protocol' for method parameter type Protocol is not present"
}

Remove Endpoint

DELETE /v1/services/{uusid}/endpoints/{id}

Removes a service endpoint.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 43. /v1/services/{uusid}/endpoints/{id}
Parameter Description

uusid

ID of service to update.

id

Unique ID of endpoint to remove.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/het/endpoints/33' -i -X DELETE

Example Response

DELETE /v1/services/het/endpoints/33 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 102

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Endpoint with ID 8675309 not found"
}

Password

POST /v1/services/{uusid}/password/{action}

Updates the password for the given service. This operation is formulated as an operational endpoint since password management is a write-only operation; thus it makes no sense to model it as a sub-resource collection. e.g. /services/a-service/passwords/123, where CRUD operations are implied.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 44. /v1/services/{uusid}/password/{action}
Parameter Description

uusid

ID of service to update.

action

Action to take on the service password: add Generate and add a new active password to the service. remove Remove (disable) the current active password, if one exists.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/add.self-service/password/add' -i -X POST

Example Response

POST /v1/services/add.self-service/password/add HTTP/1.1
Host: api.middleware.vt.edu
Content-Type: application/x-www-form-urlencoded

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Add Certificate

POST /v1/services/{uusid}/certificates

Adds a certificate to the given service.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 45. /v1/services/{uusid}/certificates
Parameter Description

uusid

ID of the service to update.

Form Parameters

Parameter Optional Description

pem

false

PEM encoded X.509 certificate.

use

true

Optional usage criteria. One of [ auth, enc, sig ]

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/middleware-test/certificates' -i -X POST \
    -d 'pem=-----BEGIN+CERTIFICATE-----%0AMIID2zCCAsOgAwIBAgIUVSYCXvYwi6W7KlUJqITK2XeKi7UwDQYJKoZIhvcNAQEL%0ABQAwfDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApC%0AbGFja3NidXJnMRYwFAYDVQQKDA1WaXJnaW5pYSBUZWNoMRMwEQYDVQQLDApNaWRk%0AbGV3YXJlMRgwFgYDVQQDDA9taWRkbGV3YXJlLXRlc3QwIBcNMjAwNjMwMTk1NzUy%0AWhgPMjEyMDA2MDYxOTU3NTJaMHwxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJn%0AaW5pYTETMBEGA1UEBwwKQmxhY2tzYnVyZzEWMBQGA1UECgwNVmlyZ2luaWEgVGVj%0AaDETMBEGA1UECwwKTWlkZGxld2FyZTEYMBYGA1UEAwwPbWlkZGxld2FyZS10ZXN0%0AMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm2J4NQr08X7TzVjzqz4S%0Aeogr6RmaTG0qs5YGQwfa8PZT0VE%2F%2Fa6O5dYSFhB6ATMriUMeQ%2BSP%2BehbZtYkkt8w%0ASPS%2FNRiZ5OP4dTeHp%2BasxgZPidpXZlyjII2T2JeEr8XlPEUtX0%2BNBhmU6cGhr6In%0ApxU5No4cu7UqV84YE3%2Bd4yDYg643j5UPrfT5KZLY28rXAkQqtbbEEbsCLvw%2FCTuF%0AF2I3pmT8XSOnrz7LQ6xRyJeJlOLDxlqF3ZwSukUQnivkJ6KxPpoe%2FEpiXadwUmQk%0AUHywdFgCi7F%2FqYY3JpI%2BqOC5jOU4aF%2F2CKlvzhQRSYbS%2ByvDZUaydOf%2Bil0Lb6HJ%0AWwIDAQABo1MwUTAdBgNVHQ4EFgQUg588qnPIR1A0PoJBztxJWPWRqNMwHwYDVR0j%0ABBgwFoAUg588qnPIR1A0PoJBztxJWPWRqNMwDwYDVR0TAQH%2FBAUwAwEB%2FzANBgkq%0AhkiG9w0BAQsFAAOCAQEAkfUA%2Faf5vie3f98c1hddcma9%2BCavp7Gdkj0bj4Xy1aZ9%0A1uFA1MO%2BPeCEu29eaHf4Ll5aKZSNdDcSvR7zS14HZc090u9d5enpk9vH2fViZR2W%0AbEfkWCc5t6AqySAh1GUmngvRlYqocOZitjpGfnAGf3TYsNDsjnnxJYykiCowbNsW%0AKxyM%2FqUtluR5ewY1B%2B9yIu78sVFKwAneW%2BxMNZCHbiJHEHNPQSkPm7x77%2BgyTMK3%0Af2D1tm8pJ42%2F4cK6QocWMtTGapQGXmiTzN%2Bvt452SjFF%2Fu3Zol6nT2TOWu0qsmO1%0A4lkPyThjCRCazV7MpXwPexAifadJcsvIYlVoq2XkYQ%3D%3D%0A-----END+CERTIFICATE-----&use=sig'

Example Response

POST /v1/services/middleware-test/certificates HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 1512

pem=-----BEGIN+CERTIFICATE-----%0AMIID2zCCAsOgAwIBAgIUVSYCXvYwi6W7KlUJqITK2XeKi7UwDQYJKoZIhvcNAQEL%0ABQAwfDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApC%0AbGFja3NidXJnMRYwFAYDVQQKDA1WaXJnaW5pYSBUZWNoMRMwEQYDVQQLDApNaWRk%0AbGV3YXJlMRgwFgYDVQQDDA9taWRkbGV3YXJlLXRlc3QwIBcNMjAwNjMwMTk1NzUy%0AWhgPMjEyMDA2MDYxOTU3NTJaMHwxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJn%0AaW5pYTETMBEGA1UEBwwKQmxhY2tzYnVyZzEWMBQGA1UECgwNVmlyZ2luaWEgVGVj%0AaDETMBEGA1UECwwKTWlkZGxld2FyZTEYMBYGA1UEAwwPbWlkZGxld2FyZS10ZXN0%0AMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm2J4NQr08X7TzVjzqz4S%0Aeogr6RmaTG0qs5YGQwfa8PZT0VE%2F%2Fa6O5dYSFhB6ATMriUMeQ%2BSP%2BehbZtYkkt8w%0ASPS%2FNRiZ5OP4dTeHp%2BasxgZPidpXZlyjII2T2JeEr8XlPEUtX0%2BNBhmU6cGhr6In%0ApxU5No4cu7UqV84YE3%2Bd4yDYg643j5UPrfT5KZLY28rXAkQqtbbEEbsCLvw%2FCTuF%0AF2I3pmT8XSOnrz7LQ6xRyJeJlOLDxlqF3ZwSukUQnivkJ6KxPpoe%2FEpiXadwUmQk%0AUHywdFgCi7F%2FqYY3JpI%2BqOC5jOU4aF%2F2CKlvzhQRSYbS%2ByvDZUaydOf%2Bil0Lb6HJ%0AWwIDAQABo1MwUTAdBgNVHQ4EFgQUg588qnPIR1A0PoJBztxJWPWRqNMwHwYDVR0j%0ABBgwFoAUg588qnPIR1A0PoJBztxJWPWRqNMwDwYDVR0TAQH%2FBAUwAwEB%2FzANBgkq%0AhkiG9w0BAQsFAAOCAQEAkfUA%2Faf5vie3f98c1hddcma9%2BCavp7Gdkj0bj4Xy1aZ9%0A1uFA1MO%2BPeCEu29eaHf4Ll5aKZSNdDcSvR7zS14HZc090u9d5enpk9vH2fViZR2W%0AbEfkWCc5t6AqySAh1GUmngvRlYqocOZitjpGfnAGf3TYsNDsjnnxJYykiCowbNsW%0AKxyM%2FqUtluR5ewY1B%2B9yIu78sVFKwAneW%2BxMNZCHbiJHEHNPQSkPm7x77%2BgyTMK3%0Af2D1tm8pJ42%2F4cK6QocWMtTGapQGXmiTzN%2Bvt452SjFF%2Fu3Zol6nT2TOWu0qsmO1%0A4lkPyThjCRCazV7MpXwPexAifadJcsvIYlVoq2XkYQ%3D%3D%0A-----END+CERTIFICATE-----&use=sig

Example Error Response

HTTP/1.1 409 Conflict
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 148

{
  "type" : "FoundException",
  "code" : 409,
  "message" : "Certificate with ID 486111850375927026925710017908841856405105970101 already exists"
}

Remove Certificate

DELETE /v1/services/{uusid}/certificates/{serial}

Removes the certificate with the given serial from the given service.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Path Parameters

Table 46. /v1/services/{uusid}/certificates/{serial}
Parameter Description

uusid

ID of the service to update.

serial

Serial number in decimal representation.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/middleware-test/certificates/486111850375927026925710017908841856405105970101' -i -X DELETE

Example Response

DELETE /v1/services/middleware-test/certificates/486111850375927026925710017908841856405105970101 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Certificate with ID 123456 not found"
}

Manage Attribute Aliases

PATCH /v1/services/z-service

Sample patch demonstrating how to manage attribute aliases. Use of the test operation is strongly recommended to ensure indices have not changed under concurrency.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/services ].

Example Request

$ curl 'https://api.middleware.vt.edu/v1/services/z-service' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/attributeAliases/0/alias","value":null},{"op":"replace","path":"/attributeAliases/1/alias","value":"mailPreferredAddress"},{"op":"test","path":"/attributeAliases/2/name","value":"uupid"},{"op":"replace","path":"/attributeAliases/2/alias","value":"username"}]'

Example Response

PATCH /v1/services/z-service HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 284
Host: api.middleware.vt.edu

[{"op":"replace","path":"/attributeAliases/0/alias","value":null},{"op":"replace","path":"/attributeAliases/1/alias","value":"mailPreferredAddress"},{"op":"test","path":"/attributeAliases/2/name","value":"uupid"},{"op":"replace","path":"/attributeAliases/2/alias","value":"username"}]

Example Error Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Token Resource API

Send OTP

POST /v1/tokens

Creates a token with a 6-digit OTP and sends the code to a recipient given by any of the following parameters: -email - email address - sms - mobile phone number (via SMS) - voice - phone number (via phone call). At least one of the above parameters is required. If multiple parameters are provided, only the first from the list above is used (in that order).

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/tokens ].

Form Parameters

Parameter Optional Description

scope

false

Purpose of token.

Must be one of: [ ACCOUNT_ACTIVATION, ACCOUNT_CREATION, AUTHENTICATION, PASSWORD_RESET ]

type

true

Optional token type; MUST be "otp" if provided.

email

true

OTP recipient email address.

sms

true

OTP recipient mobile phone number.

voice

true

OTP recipient phone number.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/tokens' -i -X POST \
    -d 'type=otp&email=somebody%40gmail.com&scope=password_reset'

Example Response

POST /v1/tokens HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 56

type=otp&email=somebody%40gmail.com&scope=password_reset

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 190

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'no_such_thing'. Valid types: [ ACCOUNT_CREATION, ACCOUNT_ACTIVATION, AUTHENTICATION, PASSWORD_RESET ]"
}

Validate

GET /v1/tokens/{id}

Validates a token by looking it up by ID/handle and verifying that it is still within its validity period.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/tokens ].

Path Parameters

Table 47. /v1/tokens/{id}
Parameter Description

id

Token identifier/handle.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/tokens/FpsLWEcf5YpMULQa91cq25x2Hqk' -i -X GET

Example Response

GET /v1/tokens/FpsLWEcf5YpMULQa91cq25x2Hqk HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Validate OTP

GET /v1/tokens

Validates an OTP by looking up the token that bears it and ensuring it is within its validity period. The recipient address where the OTP was delivered may be specified by either an email address or a phone number, but one or the other is required.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/tokens ].

Query Parameters

Parameter Optional Description

code

false

OTP code.

email

true

Email address of OTP recipient.

phone

true

Phone number of OTP recipient.

Example Request

$ curl 'https://api.middleware.vt.edu/v1/tokens?code=718359&email=somebody%40example.com' -i -X GET

Example Response

GET /v1/tokens?code=718359&email=somebody%40example.com HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 401 Unauthorized
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 90

{
  "type" : "CredentialExpiredException",
  "code" : 401,
  "message" : "Expired token"
}

User Resource API

Fetch

GET /v2/users/{uid}

Fetches the user with the given unique identifier.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 48. /v2/users/{uid}
Parameter Description

uid

UID of user to fetch.

Query Parameters

Parameter Optional Description

with

true

Zero or more optional sections of fields to include in fetched user resource.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/7100001?with=all' -i -X GET

Example Response

GET /v2/users/7100001?with=all HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 99

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "User with ID 12345671 not found"
}

Fetch Property

GET /v2/users/{uid}/{property}

Fetches a collection of subordinate resources of a user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 49. /v2/users/{uid}/{property}
Parameter Description

uid

UID of user to fetch.

property

Sub-resource collection of the user to be fetched.

Must be one of: [ ADDRESSES, AFFILIATIONS, CERTIFICATES, EMAILS, IDENTIFIERS, IMIDS, MAILBOXES, NAMES, PHONES, SUPPRESSIONS, URIS ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012267/addresses' -i -X GET

Example Response

GET /v2/users/20012267/addresses HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 228

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'employee'. Valid types: [ ADDRESSES, AFFILIATIONS, CERTIFICATES, EMAILS, IDENTIFIERS, IMIDS, MAILBOXES, NAMES, PHONES, SUPPRESSIONS, URIS ]"
}

Query

GET /v2/users

Fetches a collection of user resources based on query terms.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Query Parameters

Parameter Optional Description

affiliation

true

User affiliation

appl

true

External email address of type APPLICANT_EMAIL

ext

true

External email address of any type

first

true

First name

last

true

Last name

mail

true

Mailbox primary or alias

person

true

Associated person uid

phone

true

Phone number

pidm

true

Banner PIDM

sponsor

true

Sponsor of the service account

uupid

true

Account identifier, username or email

vtid

true

Virginia Tech ID

with

true

Zero or more optional sections of fields to include in fetched user resources.

page

true

Page you want to retrieve. Must be greater than 0. Defaults to 1 if not provided.

size

true

Size of the page you want to retrieve. Must be greater than 0.

sort

true

How the results should be sorted. Multiple sort parameters can be provided if the results should be sorted on multiple properties. By default, results are sorted by id in ascending order.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users?with=all&last=jones&page=3&size=2&sort=id%2Casc' -i -X GET

Example Response

GET /v2/users?with=all&last=jones&page=3&size=2&sort=id%2Casc HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Create HA

POST /v2/users

Creates a user with high identity assurance that is uniquely identified in Banner by the given PIDM.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Form Parameters

Parameter Optional Description

pidm

false

Banner PIDM. No validation is performed on this value other than basic character set check.

first

false

Person first name.

last

false

Person last name.

affiliation

false

Set of user affiliations.

prefix

true

Person name prefix/title of address, e.g. Mr., Ms., His Excellency.

middle

true

Person middle name.

suffix

true

Person name suffix, e.g. Jr, Sr., III.

birth

true

Birth date.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users' -i -X POST \
    -d 'pidm=51234&first=Baden&last=Powell&prefix=Sir&affiliation=VT-ACTIVE-MEMBER&affiliation=VT-FACULTY'

Example Response

POST /v2/users HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 97

pidm=51234&first=Baden&last=Powell&prefix=Sir&affiliation=VT-ACTIVE-MEMBER&affiliation=VT-FACULTY

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Create LA

POST /v2/users

Creates a user with low identity assurance.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Form Parameters

Parameter Optional Description

first

false

Person first name.

last

false

Person last name.

affiliation

false

Set of user affiliations.

prefix

true

Person name prefix/title of address, e.g. Mr., Ms., His Excellency.

middle

true

Person middle name.

suffix

true

Person name suffix, e.g. Jr, Sr., III.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users' -i -X POST \
    -d 'first=Fuzzy&middle=Little&last=Lumpkins&affiliation=VT-GUEST'

Example Response

POST /v2/users HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 60

first=Fuzzy&middle=Little&last=Lumpkins&affiliation=VT-GUEST

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Delete

DELETE /v2/users/{uid}

Deletes the user. Person is not deleted.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 50. /v2/users/{uid}
Parameter Description

uid

UID of user.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012146' -i -X DELETE

Example Response

DELETE /v2/users/20012146 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 106

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "User with ID 896745232435657 not found"
}

Link

POST /v2/users/{uid}/link/{personUid}

Associates a user with a different person using a type-specific merging strategy.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 51. /v2/users/{uid}/link/{personUid}
Parameter Description

uid

UID of user to link.

personUid

UID of person to associate with the user.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012280/link/20012277' -i -X POST

Example Response

POST /v2/users/20012280/link/20012277 HTTP/1.1
Host: api.middleware.vt.edu
Content-Type: application/x-www-form-urlencoded

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Add Certificate

POST /v2/users/{uid}/certificates

Adds an X.509 or S/MIME certificate to the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 52. /v2/users/{uid}/certificates
Parameter Description

uid

UID of user.

Form Parameters

Parameter Optional Description

type

false

Type of certificate.

Must be one of: [ SMIME, X509 ]

cert

false

PEM-encoded certificate.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012095/certificates' -i -X POST \
    -d 'type=SMIME&cert=-----BEGIN+CERTIFICATE-----%0AMIID2zCCAsOgAwIBAgIUVSYCXvYwi6W7KlUJqITK2XeKi7UwDQYJKoZIhvcNAQEL%0ABQAwfDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApC%0AbGFja3NidXJnMRYwFAYDVQQKDA1WaXJnaW5pYSBUZWNoMRMwEQYDVQQLDApNaWRk%0AbGV3YXJlMRgwFgYDVQQDDA9taWRkbGV3YXJlLXRlc3QwIBcNMjAwNjMwMTk1NzUy%0AWhgPMjEyMDA2MDYxOTU3NTJaMHwxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJn%0AaW5pYTETMBEGA1UEBwwKQmxhY2tzYnVyZzEWMBQGA1UECgwNVmlyZ2luaWEgVGVj%0AaDETMBEGA1UECwwKTWlkZGxld2FyZTEYMBYGA1UEAwwPbWlkZGxld2FyZS10ZXN0%0AMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm2J4NQr08X7TzVjzqz4S%0Aeogr6RmaTG0qs5YGQwfa8PZT0VE%2F%2Fa6O5dYSFhB6ATMriUMeQ%2BSP%2BehbZtYkkt8w%0ASPS%2FNRiZ5OP4dTeHp%2BasxgZPidpXZlyjII2T2JeEr8XlPEUtX0%2BNBhmU6cGhr6In%0ApxU5No4cu7UqV84YE3%2Bd4yDYg643j5UPrfT5KZLY28rXAkQqtbbEEbsCLvw%2FCTuF%0AF2I3pmT8XSOnrz7LQ6xRyJeJlOLDxlqF3ZwSukUQnivkJ6KxPpoe%2FEpiXadwUmQk%0AUHywdFgCi7F%2FqYY3JpI%2BqOC5jOU4aF%2F2CKlvzhQRSYbS%2ByvDZUaydOf%2Bil0Lb6HJ%0AWwIDAQABo1MwUTAdBgNVHQ4EFgQUg588qnPIR1A0PoJBztxJWPWRqNMwHwYDVR0j%0ABBgwFoAUg588qnPIR1A0PoJBztxJWPWRqNMwDwYDVR0TAQH%2FBAUwAwEB%2FzANBgkq%0AhkiG9w0BAQsFAAOCAQEAkfUA%2Faf5vie3f98c1hddcma9%2BCavp7Gdkj0bj4Xy1aZ9%0A1uFA1MO%2BPeCEu29eaHf4Ll5aKZSNdDcSvR7zS14HZc090u9d5enpk9vH2fViZR2W%0AbEfkWCc5t6AqySAh1GUmngvRlYqocOZitjpGfnAGf3TYsNDsjnnxJYykiCowbNsW%0AKxyM%2FqUtluR5ewY1B%2B9yIu78sVFKwAneW%2BxMNZCHbiJHEHNPQSkPm7x77%2BgyTMK3%0Af2D1tm8pJ42%2F4cK6QocWMtTGapQGXmiTzN%2Bvt452SjFF%2Fu3Zol6nT2TOWu0qsmO1%0A4lkPyThjCRCazV7MpXwPexAifadJcsvIYlVoq2XkYQ%3D%3D%0A-----END+CERTIFICATE-----'

Example Response

POST /v2/users/20012095/certificates HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 1516

type=SMIME&cert=-----BEGIN+CERTIFICATE-----%0AMIID2zCCAsOgAwIBAgIUVSYCXvYwi6W7KlUJqITK2XeKi7UwDQYJKoZIhvcNAQEL%0ABQAwfDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApC%0AbGFja3NidXJnMRYwFAYDVQQKDA1WaXJnaW5pYSBUZWNoMRMwEQYDVQQLDApNaWRk%0AbGV3YXJlMRgwFgYDVQQDDA9taWRkbGV3YXJlLXRlc3QwIBcNMjAwNjMwMTk1NzUy%0AWhgPMjEyMDA2MDYxOTU3NTJaMHwxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJn%0AaW5pYTETMBEGA1UEBwwKQmxhY2tzYnVyZzEWMBQGA1UECgwNVmlyZ2luaWEgVGVj%0AaDETMBEGA1UECwwKTWlkZGxld2FyZTEYMBYGA1UEAwwPbWlkZGxld2FyZS10ZXN0%0AMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm2J4NQr08X7TzVjzqz4S%0Aeogr6RmaTG0qs5YGQwfa8PZT0VE%2F%2Fa6O5dYSFhB6ATMriUMeQ%2BSP%2BehbZtYkkt8w%0ASPS%2FNRiZ5OP4dTeHp%2BasxgZPidpXZlyjII2T2JeEr8XlPEUtX0%2BNBhmU6cGhr6In%0ApxU5No4cu7UqV84YE3%2Bd4yDYg643j5UPrfT5KZLY28rXAkQqtbbEEbsCLvw%2FCTuF%0AF2I3pmT8XSOnrz7LQ6xRyJeJlOLDxlqF3ZwSukUQnivkJ6KxPpoe%2FEpiXadwUmQk%0AUHywdFgCi7F%2FqYY3JpI%2BqOC5jOU4aF%2F2CKlvzhQRSYbS%2ByvDZUaydOf%2Bil0Lb6HJ%0AWwIDAQABo1MwUTAdBgNVHQ4EFgQUg588qnPIR1A0PoJBztxJWPWRqNMwHwYDVR0j%0ABBgwFoAUg588qnPIR1A0PoJBztxJWPWRqNMwDwYDVR0TAQH%2FBAUwAwEB%2FzANBgkq%0AhkiG9w0BAQsFAAOCAQEAkfUA%2Faf5vie3f98c1hddcma9%2BCavp7Gdkj0bj4Xy1aZ9%0A1uFA1MO%2BPeCEu29eaHf4Ll5aKZSNdDcSvR7zS14HZc090u9d5enpk9vH2fViZR2W%0AbEfkWCc5t6AqySAh1GUmngvRlYqocOZitjpGfnAGf3TYsNDsjnnxJYykiCowbNsW%0AKxyM%2FqUtluR5ewY1B%2B9yIu78sVFKwAneW%2BxMNZCHbiJHEHNPQSkPm7x77%2BgyTMK3%0Af2D1tm8pJ42%2F4cK6QocWMtTGapQGXmiTzN%2Bvt452SjFF%2Fu3Zol6nT2TOWu0qsmO1%0A4lkPyThjCRCazV7MpXwPexAifadJcsvIYlVoq2XkYQ%3D%3D%0A-----END+CERTIFICATE-----

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Remove Certificate

DELETE /v2/users/{uid}/certificates/{type}

Deletes a certificate determined by the given type.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 53. /v2/users/{uid}/certificates/{type}
Parameter Description

uid

UID of user.

type

Type of certificate.

Must be one of: [ SMIME, X509 ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20011661/certificates/x509' -i -X DELETE

Example Response

DELETE /v2/users/20011661/certificates/x509 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 102

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Certificate with ID X509 not found"
}

Add External Email Address

POST /v2/users/{uid}/emails

Adds an external email address to the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 54. /v2/users/{uid}/emails
Parameter Description

uid

UID of user.

Form Parameters

Parameter Optional Description

type

false

Type of external address. [ appl = applicant, dsp = display email, prc = password recovery email, vcm = VCOM email ].

Must be one of: [ APPL, DSP, PRC, VCM ]

address

false

External email address to add.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012606/emails' -i -X POST \
    -d 'type=DSP&address=Hammy%40icloud.com'

Example Response

POST /v2/users/20012606/emails HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 35

type=DSP&address=Hammy%40icloud.com

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 131

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'GST'. Valid types: [ APPL, DSP, PRC, VCM ]"
}

Remove External Email Address

DELETE /v2/users/{uid}/emails/{typeCode}

Deletes the given type of external email address from the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 55. /v2/users/{uid}/emails/{typeCode}
Parameter Description

uid

UID of user.

typeCode

Identifier type to remove. [ appl = applicant, dsp = display email, prc = password recovery email, vcm = VCOM email ].

Must be one of: [ APPL, DSP, PRC, VCM ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012476/emails/prc' -i -X DELETE

Example Response

DELETE /v2/users/20012476/emails/prc HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 131

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'gst'. Valid types: [ APPL, DSP, PRC, VCM ]"
}

Add Identifier

POST /v2/users/{uid}/identifiers

Adds an identifier to the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 56. /v2/users/{uid}/identifiers
Parameter Description

uid

UID of user.

Form Parameters

Parameter Optional Description

type

false

Identifier type to add.

Must be one of: [ COAID, PAIRWISEID, PIDM, UDCID, VTID ]

id

false

Value (ID) of the new identifier.

context

false

Optional context that conveys the relying party identifier to which the given pairwise ID is targeted.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012386/identifiers' -i -X POST \
    -d 'type=pairwiseid&id=ES4F6ESDBPVVHS7ZXRAV2ZJKASDR25KMZLVKSJKJXKWZ42N63PMA%3D%3D%3D%3D%40vt.edu&context=service-a'

Example Response

POST /v2/users/20012386/identifiers HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 110

type=pairwiseid&id=ES4F6ESDBPVVHS7ZXRAV2ZJKASDR25KMZLVKSJKJXKWZ42N63PMA%3D%3D%3D%3D%40vt.edu&context=service-a

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 152

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'unknown'. Valid types: [ COAID, PIDM, UDCID, VTID, PAIRWISEID ]"
}

Remove Identifier

DELETE /v2/users/{uid}/identifiers/{type}

Deletes the given type of identifier from the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 57. /v2/users/{uid}/identifiers/{type}
Parameter Description

uid

UID of user.

type

Identifier type to remove.

Must be one of: [ COAID, PAIRWISEID, PIDM, UDCID, VTID ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012429/identifiers/coaid' -i -X DELETE

Example Response

DELETE /v2/users/20012429/identifiers/coaid HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 153

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'entityid'. Valid types: [ COAID, PIDM, UDCID, VTID, PAIRWISEID ]"
}

Add Address

POST /v2/users/{uid}/addresses

Adds an address of a particular type to the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 58. /v2/users/{uid}/addresses
Parameter Description

uid

UID of user.

Form Parameters

Parameter Optional Description

type

false

Type of address.

Must be one of: [ HOME, LOCAL, OFFICE, SELF_REPORTED ]

state

true

State/province code.

unlisted

true

Flag to set whether the address should be published. True for unpublished. Defaults to false.

street1

true

First part of street address.

street2

true

Second part of street address.

street3

true

Third part of street address.

pobox

true

Post office box.

city

true

City name.

zip

true

Postal code.

country

true

ISO 3166 (alpha-2) country code.See <a>https://www.iso.org/obp/ui/#search</a>; for a list.

mailStop

true

MailStop (4 digit number).

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20011802/addresses' -i -X POST \
    -d 'type=office&unlisted=true&street1=1700+Pratt+Drive&street2=Andrews+Information+Building&street3=Room+111&pobox=1234&city=Blacksburg&state=VA&zip=24060&country=US'

Example Response

POST /v2/users/20011802/addresses HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 161

type=office&unlisted=true&street1=1700+Pratt+Drive&street2=Andrews+Information+Building&street3=Room+111&pobox=1234&city=Blacksburg&state=VA&zip=24060&country=US

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Remove Address

DELETE /v2/users/{uid}/addresses/{type}

Deletes the address of the given type from the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 59. /v2/users/{uid}/addresses/{type}
Parameter Description

uid

UID of user.

type

Address type to remove.

Must be one of: [ HOME, LOCAL, OFFICE, SELF_REPORTED ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20011742/addresses/local' -i -X DELETE

Example Response

DELETE /v2/users/20011742/addresses/local HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Update Address

PATCH /v2/users/{uid}/addresses/{type}

Updates a user’s address.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 60. /v2/users/{uid}/addresses/{type}
Parameter Description

uid

UID of user.

type

Type of address.

Must be one of: [ HOME, LOCAL, OFFICE, SELF_REPORTED ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012231/addresses/home' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/street1","value":"My New St."},{"op":"replace","path":"/street2","value":"New Street 2"},{"op":"replace","path":"/unlisted","value":true}]'

Example Response

PATCH /v2/users/20012231/addresses/home HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 164
Host: api.middleware.vt.edu

[{"op":"replace","path":"/street1","value":"My New St."},{"op":"replace","path":"/street2","value":"New Street 2"},{"op":"replace","path":"/unlisted","value":true}]

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 98

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Address with ID HOME not found"
}

Add Name

POST /v2/users/{uid}/names

Adds a name to the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 61. /v2/users/{uid}/names
Parameter Description

uid

UID of user.

Form Parameters

Parameter Optional Description

type

false

Type of name.

Must be one of: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ]

first

false

First name.

last

false

Last name.

prefix

true

Name prefix.

middle

true

Middle name.

suffix

true

Name suffix.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012058/names' -i -X POST \
    -d 'type=preferred&first=john&last=doe&prefix=Mr.&suffix=Jr.&middle=deer'

Example Response

POST /v2/users/20012058/names HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 68

type=preferred&first=john&last=doe&prefix=Mr.&suffix=Jr.&middle=deer

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 158

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'unknown'. Valid types: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ]"
}

Remove Name

DELETE /v2/users/{uid}/names/{type}

Deletes the given type of name from the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 62. /v2/users/{uid}/names/{type}
Parameter Description

uid

UID of user.

type

Name type to remove.

Must be one of: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20011863/names/preferred' -i -X DELETE

Example Response

DELETE /v2/users/20011863/names/preferred HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 158

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'unknown'. Valid types: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ]"
}

Update Name

PATCH /v2/users/{uid}/names/{type}

Updates the name based on the given type.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 63. /v2/users/{uid}/names/{type}
Parameter Description

uid

UID of user.

type

Name type to update.

Must be one of: [ BANNER, EXTERNAL, PREFERRED, SELF_REPORTED ]

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012301/names/preferred' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/first","value":"Alice"},{"op":"replace","path":"/last","value":"Adams"}]'

Example Response

PATCH /v2/users/20012301/names/preferred HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 98
Host: api.middleware.vt.edu

[{"op":"replace","path":"/first","value":"Alice"},{"op":"replace","path":"/last","value":"Adams"}]

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 99

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Name with ID EXTERNAL not found"
}

Add Phone

POST /v2/users/{uid}/phones

Adds a self-reported phone number to the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 64. /v2/users/{uid}/phones
Parameter Description

uid

UID of user.

Form Parameters

Parameter Optional Description

number

false

Phone number digits.

type

false

Phone number type.

Must be one of: [ FAX, HOME, LOCAL, MOBILE, OFFICE, PAGER, SELF_REPORTED, SMS ]

country

true

ISO 3166 (alpha-2) country code. See <a>https://www.iso.org/obp/ui/#search</a>; for a list.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/2443257202524752/phones' -i -X POST \
    -d 'type=SELF_REPORTED&number=33511223344&country=FR'

Example Response

POST /v2/users/2443257202524752/phones HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 48

type=SELF_REPORTED&number=33511223344&country=FR

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Remove Phone

DELETE /v2/users/{uid}/phones/{phoneUid}

Deletes the given phone number.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 65. /v2/users/{uid}/phones/{phoneUid}
Parameter Description

uid

UID of user.

phoneUid

Unique identifier of phone number to delete.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/2443252526539641/phones/56' -i -X DELETE

Example Response

DELETE /v2/users/2443252526539641/phones/56 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 99

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Phone with ID 1234567 not found"
}

Update Phone

PATCH /v2/users/{uid}/phones/{phoneUid}

Updates the given phone number.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 66. /v2/users/{uid}/phones/{phoneUid}
Parameter Description

uid

UID of user.

phoneUid

Unique identifier of phone number to update.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/2443231480655655/phones/48' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/countryCode","value":"MX"}]'

Example Response

PATCH /v2/users/2443231480655655/phones/48 HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 53
Host: api.middleware.vt.edu

[{"op":"replace","path":"/countryCode","value":"MX"}]

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 92

{
  "type" : "AuthorizationDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Add Social Identifier

POST /v2/users/{uid}/{type}

Adds an instant messaging ID/website to the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 67. /v2/users/{uid}/{type}
Parameter Description

uid

UID of user.

type

Social identifier type to add.

Must be one of: [ IMIDS, URIS ]

Form Parameters

Parameter Optional Description

id

false

Key:value ID

Instant Messaging id:somebody@im.vt.edu. - Website:`[label]:[uri]` e.g, Web Site:http://www.vt.edu.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012223/uris' -i -X POST \
    -d 'id=awesome%3Ahttp%3A%2F%2Fnewgrounds.com'

Example Response

POST /v2/users/20012223/uris HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 40

id=awesome%3Ahttp%3A%2F%2Fnewgrounds.com

Example Error Response

HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 85

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access Denied"
}

Remove Social Identifier

DELETE /v2/users/{uid}/uris/{id}

Deletes the imid or website from the user.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 68. /v2/users/{uid}/uris/{id}
Parameter Description

uid

UID of user.

id

Id of the social identifier to remove.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012312/uris/115' -i -X DELETE

Example Response

DELETE /v2/users/20012312/uris/115 HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 95

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "Contact with ID 1 not found"
}

Is Eligible

GET /v2/users/{uid}/eligibility

Determines the eligibility for various items.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 69. /v2/users/{uid}/eligibility
Parameter Description

uid

UID of user.

Query Parameters

Parameter Optional Description

for

true

Eligibility item to be checked. If not provided, returns eligibility for all the items in the following list.class edu.vt.middleware.ed.service.UserManager$EligibilityItem

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012785/eligibility?for=TWO_FACTOR' -i -X GET

Example Response

GET /v2/users/20012785/eligibility?for=TWO_FACTOR HTTP/1.1
Host: api.middleware.vt.edu

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 192

{
  "type" : "IllegalArgumentException",
  "code" : 400,
  "message" : "Invalid type 'invalid-item'. Valid types: [ HOKIES_SECRET, NETWORK_SECRET, RECOVERY_OPTIONS, TWO_FACTOR, VT_ACCOUNT ]"
}

Update User

PATCH /v2/users/{uid}

Updates a user; only the Person#getSuppressAll() field may be updated by this method.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 70. /v2/users/{uid}
Parameter Description

uid

UID of user.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/2443253749071976' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -d '[{"op":"replace","path":"/suppressAll","value":true}]'

Example Response

PATCH /v2/users/2443253749071976 HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 53
Host: api.middleware.vt.edu

[{"op":"replace","path":"/suppressAll","value":true}]

Example Error Response

HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 104

{
  "type" : "UnsupportedOperationException",
  "code" : 400,
  "message" : "Cannot patch given field"
}

Validate SSN

POST /v2/users/{uid}/ssn/validate

Validates the last four digits of a user’s SSN.

Authorization

One of the following authentication methods is required: [ HTTP Bearer, Client TLS, Client/App HTTP Basic ] The authenticated principal must have the following entitlement(s): [ ed/rest/users ].

Path Parameters

Table 71. /v2/users/{uid}/ssn/validate
Parameter Description

uid

UID of user.

Form Parameters

Parameter Optional Description

ssn

false

Last four digits of SSN.

Example Request

$ curl 'https://api.middleware.vt.edu/v2/users/20012164/ssn/validate' -i -X POST \
    -d 'ssn=9630'

Example Response

POST /v2/users/20012164/ssn/validate HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.middleware.vt.edu
Content-Length: 8

ssn=9630

Example Error Response

HTTP/1.1 404 Not Found
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 90

{
  "type" : "NotFoundException",
  "code" : 404,
  "message" : "SSNHash does not exist"
}

Known Breaking Changes

The following section describes API changes from ED 4.x to ED 5.x. If we deemed the API to be interface compatible, the version number is unchanged; otherwise the version number incremented accordingly. The mailbox and account APIs changed dramatically as a consequence of need to evolve the data model, and these have been incremented to /v2.

General API Behavior Changes

  • Deletion: DELETE operations now return a 204 instead of a 200. This provides a clear signal that there is no content in the body to read.

  • Pagination: The parameters start and stop are no longer supported. All clients should use page and size instead. The meaning of the parameters is also different. In ED4 start:stop meant: fetch rows from index[start] to index[stop]. In this version of ED page:size means: fetch a page with -size- number of results:

    • Page=1 : Size=20 → fetch the first 20 results (1-20)

    • Page=2 : Size=20 → fetch the next 20 results (21-40)

Type Codes

Type codes have changed throughout the API to increase readability. The following table provides a mapping from the ED4 value to that of ED5.

Type

ED4

ED5

Notes

Third-Party Email

APPL

APPLICANT_EMAIL

Third-Party Email

DSP

DISPLAY_EMAIL

Third-Party Email

GST

N/A

Guest email address is an account attribute in ED5

Third-Party Email

PRC

NOTIFICATION_EMAIL

Third-Party Email

VCM

VCOM_EMAIL

Name

AN

ALUMNI

Name

BN

BANNER

Name

PN

PREFERRED

Person

Virginia Tech

VT

Person

Guest

GUEST

Person

Sponsored

N/A

Sponsor is an optional account attribute in ED5

Recovery

C4H

N/A

Call 4-Help is a materialized field in ED5: "call4Help": true/false

Recovery

O2S

OTP2SMS

Recovery

O2V

OTP2VOICE

Recovery

GRA

GOOGLE

Recovery

YRA

YAHOO

State

ACT

ACTIVE

State

LKD

LOCKED

State

PVD

UNCREDENTIALED

State

SLD

SHELVED

State

TBR

TO_BE_DELETED

Account Resource API

  • Version is now v2.

  • The URI for managing account token credentials is now /v2/accounts/tokens; it was formerly /v1/tokens.

Mailbox Resource API

  • Version is now v2.

  • Mailbox fetch and query JSON structures have changed:

    • passwordChangeDate and passwordState fields have been removed because mailboxes no longer have passwords.

    • nextStateChangeDate is deprecated. An approximation of the ED4 calculation is used.

    • routeType which was undefined in ED4 is now RouteType.NONE. The JSON for this field is now "None" rather than null.

  • Mailbox delete will throw a 404 when attempting to remove an alias that does not exist on the given mailbox.

Password Complexity API

Password rules are now returned in an array, even when type is specified.

Guest Resource API

There is no longer a dedicated endpoint for managing guests. All guest operations have been assumed by either the person API (managing demographic data) and the account API (credential creation/management). See the Invite Guest section above for the new API for sending invites to create guest accounts.