ED REST API Operations Reference

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:

Most requests require client authentication (HTTP Bearer, client TLS, or HTTP Basic)
The content type of all responses is application/json
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
Query result sort order varies by operation but strives for "natural sort order"
20x status on success
40x status on client errors (aka "Your Bad")
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:

GET - fetch a resource by ID or query for multiple resources (see subsequent section)
POST - create a new resource
PATCH - update a resource with merge semantics
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 US/Eastern 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:

2016-11-30T07:30:01-05:00 (07:30:01AM November 30, 2016 EST)
2017-01-01T00:01:20-05:00 (12:01:20AM January 1, 2017 EST)
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 US/Eastern time zone is assumed. All of the following may be used to indicate the date 12:30:00PM January 1, 2017 EST:

2017-01-01T12:30:00
2017-01-01T12:30:00-05:00
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 US/Eastern 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 ].

Path parameters

No parameters.

Query parameters

Parameter	Type	Optional	Description
vtid	String	false	Virginia Tech ID number of the person who will own the account.
username	String	false	Account username.
password	String	false	Account password.
synchronize	Boolean	true	Flag to determine if the account credential should be synchronized to other systems.

Parameter

Type

Optional

Description

vtid

String

false

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

username

String

false

Account username.

password

String

false

Account password.

synchronize

Boolean

true

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

Response fields

No response body.

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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/accounts/alice
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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 ].

Path parameters

No parameters.

Query parameters

Parameter	Type	Optional	Description
email	String	false	Recipient of the invitation.
inviter	String	true	Username of the account that initiated the invitation.
message	String	true	Personalization message to be included in the invitation email.
kv	Object	true	Zero or more pipe-delimited key-value pairs that will be added as metadata in the token.

Parameter

Type

Optional

Description

String

false

Recipient of the invitation.

inviter

String

true

Username of the account that initiated the invitation.

message

String

true

Personalization message to be included in the invitation email.

Object

true

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

Response fields

No response body.

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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/accounts/blueberry@example.com
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:(?!.*[_]{2})(?!.*[.]{2})(?!.*[-]{2})[a-z][a-z0-9_.-]{1,30}[a-z0-9]}

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

Parameter	Type	Optional	Description
identifier	String	false	Identifier of account to fetch.

Parameter

Type

Optional

Description

identifier

String

false

Identifier of account to fetch.

Query parameters

Parameter	Type	Optional	Description
with	Array[String]	true	Zero or more optional sections of fields to include in fetched account resource.

Parameter

Type

Optional

Description

with

Array[String]

true

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 105

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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Query

GET /v2/accounts

Fetches a collection of account resources based on query terms. Supported query terms:

username - identifier (username / email address) of the account
type - type of account
uid - UID identifier of the User owning 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

No parameters.

Query parameters

Supports standard paging query parameters.

Parameter	Type	Optional	Description
params	Object	false	All request parameters, may include pagination parameters.
with	Array[String]	true	Zero or more optional sections of fields to include in fetched account resources.

Parameter

Type

Optional

Description

params

Object

false

All request parameters, may include pagination parameters.

with

Array[String]

true

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

Response fields

No response body.

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

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: 1; mode=block
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: 404

[ {
  "creationDate" : "2024-04-05T23:55:55Z",
  "identifier" : "the_apple",
  "username" : "the_apple",
  "email" : null,
  "owner" : {
    "uid" : 20004461,
    "type" : "VT"
  },
  "sponsor" : null
}, {
  "creationDate" : "2024-04-05T23:55:55Z",
  "identifier" : "the_beet",
  "username" : "the_beet",
  "email" : null,
  "owner" : {
    "uid" : 20004464,
    "type" : "VT"
  },
  "sponsor" : null
} ]

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is 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

Parameter	Type	Optional	Description
identifier	String	false	Identifier of the account that will own the recovery option being set.

Parameter

Type

Optional

Description

identifier

String

false

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

Query parameters

Parameter	Type	Optional	Description
type	String	false	Type of recovery option to set. Must be one of [OTP2SMS, OTP2VOICE, GOOGLE, YAHOO].
endpoint	String	false	Information required to use the recovery option, such as phone number for OTP2SMS.

Parameter

Type

Optional

Description

type

String

false

Type of recovery option to set.

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

endpoint

String

false

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

Response fields

No response body.

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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/accounts/with-new-otp2sms
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

Example Set Google Recovery Option 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: 1; mode=block
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

Parameter	Type	Optional	Description
identifier	String	false	Identifier of the account.
type	String	false	Type of recovery option to remove. Must be one of [OTP2SMS, OTP2VOICE, GOOGLE, YAHOO].

Parameter

Type

Optional

Description

identifier

String

false

Identifier of the account.

type

String

false

Type of recovery option to remove.

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

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/accounts/remove-otp2sms
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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

Parameter	Type	Optional	Description
identifier	String	false	Identifier of the account to verify.

Parameter

Type

Optional

Description

identifier

String

false

Identifier of the account to verify.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/accounts/verify-ops-pos
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is 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

Parameter	Type	Optional	Description
identifier	String	false	Identifier of account to change.

Parameter

Type

Optional

Description

identifier

String

false

Identifier of account to change.

Query parameters

Parameter	Type	Optional	Description
new	String	false	New password for the account.
credential	String	false	Token or old password used to authenticate before changing the password.
type	String	false	Type of credential. Must be one of [GOOGLE, PASSWORD, TOKEN].
synchronize	Boolean	true	Flag to determine if the account credential should be synchronized to other systems.

Parameter

Type

Optional

Description

new

String

false

New password for the account.

credential

String

false

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

type

String

false

Type of credential.

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

synchronize

Boolean

true

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

Response fields

No response body.

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

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: 1; mode=block
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

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: 1; mode=block
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 ].

Path parameters

No parameters.

Query parameters

Parameter	Type	Optional	Description
validity	Object	true	Validity period for the token, if not given set to max validity allowed for the token scope.

Parameter

Type

Optional

Description

validity

Object

true

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

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/jwt;charset=UTF-8
Content-Length: 654
Location: https://build.api.middleware.vt.edu/v2/accounts/gamma
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1aWQ9NDg1NjgwNTcwMTIxNzI1MjIsb3U9UGVvcGxlLGRjPXZ0LGRjPWVkdSIsInBhc3N3b3JkIjoiOXRhbXVrcDE2OXB3dHJibXF6Y2lkNWd5IiwiaXNzIjoidXVzaWQ9dG9rZW5zLG91PVNlcnZpY2VzLGRjPXZ0LGRjPWVkdSIsImV4cCI6MTcxMjM2NDk1MCwiaWF0IjoxNzEyMzYxMzUwLCJqdGkiOiI5dGFtdWtwMTY5cHd0cmJtcXpjaWQ1Z3kifQ.rEU45Gmxfu1lerxbCYwppgliKSlbP33xd1i-ZcnCKAn_1REjnJFOYYHlBpbc8DgZqcVREXPZDTgOXjwN1cRmN2VCTOpm7iAlGcLV3JQ8jR5tcudyYsbsUyTJysnfOZJD6UxCJUx9JOvx9djg80fbDaaFfKdCU2R4tQQd7yDpFTTSiCNdAZOulyfpquTuVYpr2vEKvRXGSATT1b5UjCHP-OXwfDzy4tvjy8kyKjYiOGK9VsVWUOUkA0rb1sE7zhdvuA-V6gCGnFM4jIoh58rHJXVtml3S-jsRwQd_tXICCm6iU4UIH15LWpnnRGx5S1bZa_bKqNG0sviy3shQQqBaNg

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: 1; mode=block
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 ].

Path parameters

No parameters.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/accounts/zeta
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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

Parameter	Type	Optional	Description
identifier	String	false	Identifier of the account.

Parameter

Type

Optional

Description

identifier

String

false

Identifier of the account.

Query parameters

Parameter	Type	Optional	Description
pass	String	false	Active password for the account.

Parameter

Type

Optional

Description

pass

String

false

Active password for the account.

Response fields

No response body.

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

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 20
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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" : 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: 1; mode=block
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 ].

Path parameters

No parameters.

Query parameters

No parameters.

Response fields

Path	Type	Optional
code	Integer	true
summary	String	true
message	String	true
changes	Array[String]	true
errors	Array[Object]	true
errors[].type	String	true
errors[].label	String	true
errors[].message	String	true

Path

Type

Optional

Description

code

Integer

true

summary

String

true

message

String

true

changes

Array[String]

true

errors

Array[Object]

true

errors[].type

String

true

errors[].label

String

true

errors[].message

String

true

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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/persons/20003855
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

Person Partially Updated

POST /v1/replication/banner/consume

Processes a Banner PERSONSET XML message.

Authorization

Path parameters

No parameters.

Query parameters

No parameters.

Response fields

Path	Type	Optional
code	Integer	true
summary	String	true
message	String	true
changes	Array[String]	true
errors	Array[Object]	true
errors[].type	String	true
errors[].label	String	true
errors[].message	String	true

Path

Type

Optional

Description

code

Integer

true

summary

String

true

message

String

true

changes

Array[String]

true

errors

Array[Object]

true

errors[].type

String

true

errors[].label

String

true

errors[].message

String

true

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

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: 1; mode=block
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: 779

{
  "code" : 400,
  "summary" : "2 changes made to person 8675309",
  "message" : "Incomplete update of person PIDM(8675309)",
  "changes" : [ "Updated gender to FEMALE", "Updated studentConfidential flag to true" ],
  "errors" : [ {
    "type" : "ConstraintViolationException",
    "label" : "Person.identifiers",
    "message" : "addIdentifier.identifier.value: UDCID must be exactly 32 alphanumeric characters"
  }, {
    "type" : "ConstraintViolationException",
    "label" : "Person.identifiers",
    "message" : "addIdentifier.identifier.value: Virginia Tech ID must match [\\p{Alnum}]{9}"
  }, {
    "type" : "ConstraintViolationException",
    "label" : "Person.addresses",
    "message" : "addAddress.address.street3: Street 3 exceeds the maximum length of 100."
  } ]
}

Example Error Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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"
}

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

Parameter	Type	Optional	Description
name	String	false	Name of developer team to fetch.

Parameter

Type

Optional

Description

name

String

false

Name of developer team to fetch.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 56

{
  "name" : "the-a-team",
  "members" : [ "member1" ]
}

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: 1; mode=block
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 ].

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

Parameter	Type	Optional	Description
name	String	true	Optional name expression to limit results to developer teams matching the given name. Supports wildcards, e.g. `dbaa*`.
member	Integer	true	Optional member uid used to select teams containing the given member.

name

String

true

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

member

Integer

true

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 58

[ {
  "name" : "the-a-team",
  "members" : [ "alpha" ]
} ]

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is 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 ].

Path parameters

No parameters.

Query parameters

Parameter	Type	Optional	Description
name	String	false	Developer team name.
member	Object	false	One or more names of groups to nest inside the developer team group.

Parameter

Type

Optional

Description

name

String

false

Developer team name.

member

Object

false

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

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/devteams/the-b-team
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Entitlement Resource API

Fetch

GET /v1/entitlements/{id:[0-9]+}

Fetches the entitlement with the given unique identifier.

Authorization

Path parameters

Parameter	Type	Optional	Description
id	String	false	ID of entitlement.

Parameter

Type

Optional

Description

String

false

ID of entitlement.

Query parameters

Parameter	Type	Optional	Description
with	Array[String]	true	Zero or more optional sections of fields to include in fetched resource.

Parameter

Type

Optional

Description

with

Array[String]

true

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 756

{
  "creationDate" : "2024-04-05T23:56:02Z",
  "expirationDate" : null,
  "name" : "ccs/1",
  "entitlement" : "other-manager-service:ccs/1",
  "manager" : {
    "kind" : "service",
    "uusid" : "other-manager-service",
    "uuid" : "other-manager-service",
    "creationDate" : "2024-04-05T23:56:02Z",
    "expirationDate" : null,
    "uid" : 20004896
  },
  "member" : {
    "kind" : "person",
    "pid" : "bob",
    "displayName" : "Virginia302 Test",
    "creationDate" : "2024-04-05T19:56:02-04:00",
    "uid" : 20004893
  },
  "uid" : 1052,
  "viewers" : [ {
    "kind" : "service",
    "uusid" : "middleware-test",
    "uuid" : "middleware-test",
    "creationDate" : "2024-04-05T23:56:02Z",
    "expirationDate" : null,
    "uid" : 20004890
  } ]
}

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: 1; mode=block
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 10341000 not found"
}

Query

GET /v1/entitlements

Fetches a collection of entitlement resources based on query terms. Supported query terms:

person - user bearing the entitlement
service - service bearing the entitlement
group - group bearing the entitlement
owner - principal who is the owner(manager) of the entitlement
name - name of the entitlement
sponsor - sponsor of the entitlement
viewer - subject in viewer role on the entitlement

Authorization

Path parameters

No parameters.

Query parameters

Supports standard paging query parameters.

Parameter	Type	Optional	Description
params	Object	false	All request parameters, includes optional pagination parameters.
with	Array[String]	true	Zero or more optional sections of fields to include in fetched resources.

Parameter

Type

Optional

Description

params

Object

false

All request parameters, includes optional pagination parameters.

with

Array[String]

true

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 580

[ {
  "creationDate" : "2024-04-05T23:56:06Z",
  "expirationDate" : null,
  "name" : "ed/test/ent/goldfinch",
  "entitlement" : "middleware-test:ed/test/ent/goldfinch:read:write",
  "manager" : {
    "kind" : "service",
    "uusid" : "middleware-test",
    "uuid" : "middleware-test",
    "creationDate" : "2024-04-05T23:56:06Z",
    "expirationDate" : null,
    "uid" : 20005263
  },
  "member" : {
    "kind" : "person",
    "pid" : "melanie",
    "displayName" : "Virginia325 Test",
    "creationDate" : "2024-04-05T19:56:06-04:00",
    "uid" : 20005266
  },
  "uid" : 1148
} ]

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Create

POST /v2/entitlements

Creates an entitlement.

Authorization

Path parameters

No parameters.

Query parameters

Parameter	Type	Optional	Description
resource	String	false	Resource of the entitlement.
scope	String	true	Scope of the entitlement.

Parameter

Type

Optional

Description

resource

String

false

Resource of the entitlement.

scope

String

true

Scope of the entitlement.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/entitlements/20005122
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[A-Fa-f0-9-]+}

Deletes the given entitlement.

Authorization

Path parameters

Parameter	Type	Optional	Description
id	String	false	A unique identifier for the entitlement.

Parameter

Type

Optional

Description

String

false

A unique identifier for the entitlement.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

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: 1; mode=block
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

Path parameters

No parameters.

Query parameters

Parameter	Type	Optional	Description
name	String	false	Entitlement resource URI.
scope	String	true	Scope of the entitlement.
person	Integer	true	User to whom to grant the entitlement.
service	String	true	Service to which to grant the entitlement.
sponsor	Integer	true	User who initiated the granting of the entitlement. If not specified, the principal that invokes the operation is the grantor.
expiration	Object	true	Expiration date after which the granted entitlement is automatically revoked by the system.
viewer	Object	true	Zero or more service viewers of the entitlement.

Parameter

Type

Optional

Description

name

String

false

Entitlement resource URI.

scope

String

true

Scope of the entitlement.

person

Integer

true

User to whom to grant the entitlement.

service

String

true

Service to which to grant the entitlement.

sponsor

Integer

true

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

expiration

Object

true

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

viewer

Object

true

Zero or more service viewers of the entitlement.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/entitlements//20004722
Content-Location: https://build.api.middleware.vt.edu/v1/entitlements//1012
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

====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: 1; mode=block
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:[0-9]+}

Revokes the given grant (equivalent of EDv4 entitlement).

Authorization

Path parameters

Parameter	Type	Optional	Description
id	Integer	false	ID of grant.

Parameter

Type

Optional

Description

Integer

false

ID of grant.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

====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: 1; mode=block
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:[0-9]+}/viewers

Adds the given service viewers to an existing entitlement.

Authorization

Path parameters

Parameter	Type	Optional	Description
uid	String	false	ID of grant.

Parameter

Type

Optional

Description

uid

String

false

ID of grant.

Query parameters

Parameter	Type	Optional	Description
expiration	String	true	Expiration date of viewer role.
viewer	Array[String]	false	Username of services to add as viewers of the entitlement.

Parameter

Type

Optional

Description

expiration

String

true

Expiration date of viewer role.

viewer

Array[String]

false

Username of services to add as viewers of the entitlement.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/entitlements/1037
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

====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: 1; mode=block
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 20005013 already exists"
}

Remove Viewer

DELETE /v1/entitlements/{uid:[0-9]+}/viewers/{id:^[a-z][a-z0-9_.-]+}

Removes the given service viewer from an existing entitlement.

Authorization

Path parameters

Parameter	Type	Optional	Description
uid	String	false	ID of grant.
id	String	false	Username of service viewer to remove.

Parameter

Type

Optional

Description

uid

String

false

ID of grant.

String

false

Username of service viewer to remove.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

====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: 1; mode=block
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 20004755 not found"
}

Update Relation

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

Updates the entitlement relation given a JSON patch.

Authorization

Path parameters

Parameter	Type	Optional	Description
uid	String	false	ID of grant.
role	String	false	Entitlement role. At present, only viewers are supported.
id	String	false	Username of service to update.

Parameter

Type

Optional

Description

uid

String

false

ID of grant.

role

String

false

Entitlement role. At present, only viewers are supported.

String

false

Username of service to update.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

====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: 1; mode=block
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:[a-z0-9]{1,64}(?:\.(?:[a-z0-9]{1,64}|[a-z0-9][a-z0-9_-]{1,62}[a-z0-9]))*}

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

Parameter	Type	Optional	Description
uugid	String	false	Name of group to fetch.

Parameter

Type

Optional

Description

uugid

String

false

Name of group to fetch.

Query parameters

Parameter	Type	Optional	Description
with	Array[String]	true	Zero or more optional sections of fields to include in fetched group resource.

Parameter

Type

Optional

Description

with

Array[String]

true

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

Response fields

No response body.

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

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: 1; mode=block
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: 696

{
  "creationDate" : "2024-04-05T23:55:15Z",
  "displayName" : "Middleware Developers Group",
  "expirationDate" : "2026-04-05T19:55:15-04:00",
  "uugid" : "middleware.dvlp",
  "membership" : [ ],
  "members" : [ {
    "kind" : "person",
    "pid" : "andrew",
    "displayName" : "Somebody WithEdSecurityContext",
    "creationDate" : "2024-04-05T23:55:15Z",
    "expirationDate" : null,
    "uid" : 48568021499165402
  }, {
    "kind" : "group",
    "uugid" : "middleware.dvlp.child",
    "displayName" : null,
    "creationDate" : "2024-04-05T23:55:15Z",
    "expirationDate" : null
  } ],
  "targets" : [ "code.vt.edu", "w2k.vt.edu" ],
  "suppressDisplay" : true,
  "suppressMembers" : false
}

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: 1; mode=block
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:[a-z0-9][a-z0-9._-]+}/{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

Parameter	Type	Optional	Description
uugid	String	false	Name of group to search.
role	String	false	Role the subject belongs to on the group. Must be one of [ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS].
id	String	false	Unique identifier of the subject to fetch.

Parameter

Type

Optional

Description

uugid

String

false

Name of group to search.

role

String

false

Role the subject belongs to on the group.

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

String

false

Unique identifier of the subject to fetch.

Query parameters

Parameter	Type	Optional	Description
kind	String	true	The kind of subject. Must be one of [GROUP, PERSON, SERVICE].

Parameter

Type

Optional

Description

kind

String

true

The kind of subject.

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 170

{
  "kind" : "service",
  "uusid" : "middleware",
  "uuid" : "middleware",
  "creationDate" : "2024-04-05T19:55:17-04:00",
  "expirationDate" : null,
  "uid" : 20003431
}

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: 1; mode=block
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

Fetches a collection of group resources based on query terms. Supported query terms:

uugid - unique identifier
crafter - created date after
crbefore - created date before
exafter - expiration date after
exbefore - expiration date before
member - group member name (may be an account username identifying a person or service or group name)
child - nested group name (use this parameter if you are seaching for child groups explicitly)
administrator - subject in administrator role
contact - subject in contact role (deprecated)
manager - subject in manager role
viewer - subject in viewer role

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

No parameters.

Query parameters

Supports standard paging query parameters.

Parameter	Type	Optional	Description
params	Object	false	All request parameters, includes optional pagination parameters.
with	Array[String]	true	Zero or more optional sections of fields to include in fetched group resources.

Parameter

Type

Optional

Description

params

Object

false

All request parameters, includes optional pagination parameters.

with

Array[String]

true

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 274

[ {
  "creationDate" : "2024-04-05T23:55:20Z",
  "displayName" : null,
  "expirationDate" : null,
  "uugid" : "middleware.dvlp.group1"
}, {
  "creationDate" : "2024-04-05T23:55:20Z",
  "displayName" : null,
  "expirationDate" : null,
  "uugid" : "middleware.dvlp.group3"
} ]

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is 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 ].

Path parameters

No parameters.

Query parameters

Parameter	Type	Optional	Description
uugid	String	false	Unique group name of group to create.
contact	Object	true	One or more group contacts.
administrator	Object	true	One or more group administrators.

Parameter

Type

Optional

Description

uugid

String

false

Unique group name of group to create.

contact

Object

true

One or more group contacts.

administrator

Object

true

One or more group administrators.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/groups/test.group-1
Warning: 299 - "The contact parameter will be deprecated in the v2 REST API"
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-z0-9][a-z0-9._-]+}/{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

Parameter	Type	Optional	Description
uugid	String	false	ID of group to update.
role	String	false	Role to add members to. Must be one of [ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS].

Parameter

Type

Optional

Description

uugid

String

false

ID of group to update.

role

String

false

Role to add members to.

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

Query parameters

Parameter	Type	Optional	Description
kind	String	false	Kind of member to add. Must be one of [GROUP, PERSON, SERVICE].
id	String	false	Username or UID of subject to add. Only username is allowed for Admin and Contact.
expiration	String	true	Expiration date.

Parameter

Type

Optional

Description

kind

String

false

Kind of member to add.

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

String

false

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

expiration

String

true

Expiration date.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/groups/test.group/administrators/connie
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-z0-9][a-z0-9._-]+}/{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

Parameter	Type	Optional	Description
uugid	String	false	ID of group to update.
role	String	false	Role to remove members from. Must be one of [ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS].
id	String	false	Username or UID of subject to remove from role.

Parameter

Type

Optional

Description

uugid

String

false

ID of group to update.

role

String

false

Role to remove members from.

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

String

false

Username or UID of subject to remove from role.

Query parameters

Parameter	Type	Optional	Description
kind	String	true	Kind of member to remove. Must be one of [GROUP, PERSON, SERVICE].

Parameter

Type

Optional

Description

kind

String

true

Kind of member to remove.

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

Response fields

No response body.

Example request

$ curl 'https://api.middleware.vt.edu/v1/groups/test.group/members/pidlike?kind=person' -i -X DELETE

Example 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.group/members/pidlike
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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

Parameter	Type	Optional	Description
uugid	String	false	Group unique name.
role	String	false	Group role. Must be one of [ADMINISTRATORS, CONTACTS, MANAGERS, MEMBERS, VIEWERS].
id	String	false	Id of group relation subject to update.

Parameter

Type

Optional

Description

uugid

String

false

Group unique name.

role

String

false

Group role.

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

String

false

Id of group relation subject to update.

Query parameters

Parameter	Type	Optional	Description
kind	String	true	Kind of subject. Must be one of [GROUP, PERSON, SERVICE].

Parameter

Type

Optional

Description

kind

String

true

Kind of subject.

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

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: 1; mode=block
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

Parameter	Type	Optional	Description
uugid	String	false	Group unique name.

Parameter

Type

Optional

Description

uugid

String

false

Group unique name.

Query parameters

No parameters.

Response fields

No response body.

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":1743897314},{"op":"replace","path":"/displayName","value":"a common n-type dopant in semiconductor electronic devices"}]'

Example 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: 1; mode=block
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

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: 1; mode=block
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:[a-z0-9][a-z0-9._-]+}

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

Parameter	Type	Optional	Description
uugid	String	false	ID of group to delete.

Parameter

Type

Optional

Description

uugid

String

false

ID of group to delete.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

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: 1; mode=block
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

Parameter	Type	Optional	Description
uugid	String	false	Group to modify.

Parameter

Type

Optional

Description

uugid

String

false

Group to modify.

Query parameters

No parameters.

Response fields

No response body.

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"}]'

Example 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: 1; mode=block
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: 29

[ "ADDED", "ADDED", "ADDED" ]

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

Parameter	Type	Optional	Description
uugid	String	false	Group to modify.

Parameter

Type

Optional

Description

uugid

String

false

Group to modify.

Query parameters

No parameters.

Response fields

No response body.

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"}]'

Example 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: 1; mode=block
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: 35

[ "REMOVED", "REMOVED", "REMOVED" ]

ID Proof Resource API

Grade

POST /v1/persons/{uid:[0-9]+}/questions/{qid}/grade

Grades a single answer as a pass/fail.

Authorization

Path parameters

Parameter	Type	Optional	Description
uid	Integer	false	UID of user whose challenge question is being graded.
qid	String	false	Question id of the question being graded.

Parameter

Type

Optional

Description

uid

Integer

false

UID of user whose challenge question is being graded.

qid

String

false

Question id of the question being graded.

Query parameters

Parameter	Type	Optional	Description
answer	String	false	To be graded.

Parameter

Type

Optional

Description

answer

String

false

To be graded.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 19

{
  "pass" : true
}

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: 1; mode=block
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:[0-9]+}/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

Path parameters

Parameter

Type

Optional

Description

uid

Integer

false

UID of user whose identity challenge questions will be returned.

Query parameters

No parameters.

Response fields

Path

Type

Optional

Description

[].id

String

false

[].question

String

false

[].regex

String

false

[].options

Boolean

false

[].answers

Array[String]

false

Example request

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

Example 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: 1; mode=block
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: 364

[ {
  "id" : "fname",
  "question" : "What is your first name?",
  "regex" : ".*",
  "options" : false,
  "answers" : [ ]
}, {
  "id" : "lname",
  "question" : "What is your last name?",
  "regex" : ".*",
  "options" : false,
  "answers" : [ ]
}, {
  "id" : "bday",
  "question" : "When were you born?",
  "regex" : ".*",
  "options" : false,
  "answers" : [ ]
} ]

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Mailbox Resource API

Fetch

+GET /v2/mailboxes/{address:[a-zA-Z0-9.!#$&'*+=?^_~-]@[a-zA-Z0-9-]\.}`

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

Parameter

Type

Optional

Description

address

String

false

Address of mailbox to fetch.

Query parameters

Parameter

Type

Optional

Description

with

Array[String]

true

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

Response fields

No response body.

Example request

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

Example 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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 437

{
  "address" : "alice@vt.edu",
  "creationDate" : "2024-04-05T23:54:45Z",
  "expirationDate" : null,
  "owner" : {
    "uid" : 20001493,
    "type" : "VT"
  },
  "preferredAddress" : "alice.alias@vt.edu",
  "routeType" : "GOOGLE",
  "type" : "PERSONAL",
  "aliases" : [ "alice.alias@vt.edu" ],
  "forwards" : [ ],
  "maxAliases" : 5,
  "accountState" : {
    "reason" : "CREATED",
    "state" : "ACTIVE"
  },
  "nextTransitions" : [ ]
}

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: 1; mode=block
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

Fetches a collection of mailbox resources based on query terms. Supported query :

address - primary (MAILBOX) address of the mailbox
alias - ALIAS address of the mailbox
forward - FORWARD address of the mailbox
any - any type of address of the mailbox (MAILBOX, ALIAS, FORWARD)
username - username of the mailbox owner
type - type of the mailbox
state - state of the mailbox
uid - UID of the mailbox owner
exafter - mailbox expiring after the given date
exbefore - mailbox expiring before the given date

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

No parameters.

Query parameters

Supports standard paging query parameters.

Parameter

Type

Optional

Description

params

Object

false

All request parameters, may include pagination parameters.

with

Array[String]

true

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 413

[ {
  "address" : "no.match.3@vt.edu",
  "creationDate" : "2024-04-05T23:54:41Z",
  "expirationDate" : null,
  "owner" : {
    "uid" : 20001109,
    "type" : "EXTRINSIC"
  },
  "routeType" : "NONE",
  "type" : "FORWARDING",
  "accountState" : {
    "reason" : "CREATED",
    "state" : "ACTIVE"
  },
  "nextTransitions" : [ {
    "type" : "ADMINISTRATIVE_ACTION",
    "date" : "1970-12-31T19:00:00-05:00"
  } ]
} ]

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Add Alias

+POST /v2/mailboxes/{address:[a-zA-Z0-9.!#$&'*+=?^_~-]@[a-zA-Z0-9-]\.}/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

Parameter

Type

Optional

Description

address

String

false

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

Query parameters

Parameter

Type

Optional

Description

alias

String

false

Email address to add as an alias of the mailbox.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/mailboxes/alice@vt.edu
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-zA-Z0-9.!#$&'*+=?^_~-]@[a-zA-Z0-9-]\.}/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

Parameter

Type

Optional

Description

address

String

false

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

alias

String

false

Email address to remove from the aliases of the mailbox.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/mailboxes/alice@vt.edu
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-zA-Z0-9.!#$&'*+=?^_~-]@[a-zA-Z0-9-]\.}/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

Parameter

Type

Optional

Description

address

String

false

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

Query parameters

Parameter

Type

Optional

Description

forward

String

false

Email address to add as a forward to mailbox.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/mailboxes/alice@vt.edu
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-zA-Z0-9.!#$&'*+=?^_~-]@[a-zA-Z0-9-]\.}/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

Parameter

Type

Optional

Description

address

String

false

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

forward

String

false

Email address to remove from the forwards of the mailbox.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/mailboxes/alice@vt.edu
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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

Update

+PATCH /v2/mailboxes/{address:[a-zA-Z0-9.!#$&'*+=?^_~-]@[a-zA-Z0-9-]\.}`

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

Parameter

Type

Optional

Description

address

String

false

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

Query parameters

No parameters.

Response fields

No response body.

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

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/v2/mailboxes/primary@vt.edu
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Update Mail Route

Update

+PATCH /v2/mailboxes/{address:[a-zA-Z0-9.!#$&'*+=?^_~-]@[a-zA-Z0-9-]\.}`

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

Parameter

Type

Optional

Description

address

String

false

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

Query parameters

No parameters.

Response fields

No response body.

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

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/v2/mailboxes/alice@vt.edu
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

Example Error Response

Unresolved directive in api.adoc - include::../../../target/generated-snippets/mailbox-resource-controller-test/update-route-neg-unsupported-route/http-response.adoc[]

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

Parameter

Type

Optional

Description

namespace

String

false

The namespace to check.

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

value

String

false

The namespace value.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 20
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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" : true
}

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: 1; mode=block
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 ].

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

value

String

false

Namespace value to reserve.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/namespaces/reserved/values/rp.username
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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

Parameter

Type

Optional

Description

value

String

false

Namespace value for which to remove reservation.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

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: 1; mode=block
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.

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

userid

String

false

Userid associated with the password.

password

String

false

To check complexity.

type

Object

true

Of the userid.

with

Array[String]

true

To include in the response.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 1798

[ {
  "type" : "PID",
  "valid" : false,
  "entropy" : 28.0,
  "details" : [ {
    "errorCode" : "INSUFFICIENT_UPPERCASE",
    "parameters" : {
      "minimumRequired" : 1,
      "matchingCharacterCount" : 0,
      "validCharacters" : "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
      "matchingCharacters" : ""
    }
  }, {
    "errorCode" : "INSUFFICIENT_CHARACTERISTICS",
    "parameters" : {
      "successCount" : 0,
      "minimumRequired" : 1,
      "ruleCount" : 2
    }
  } ],
  "messages" : [ "Password must contain 1 or more uppercase letters.", "Password must contain 1 or more digits or symbols." ]
}, {
  "type" : "AD",
  "valid" : false,
  "entropy" : 28.0,
  "details" : [ {
    "errorCode" : "INSUFFICIENT_UPPERCASE",
    "parameters" : {
      "minimumRequired" : 1,
      "matchingCharacterCount" : 0,
      "validCharacters" : "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
      "matchingCharacters" : ""
    }
  }, {
    "errorCode" : "INSUFFICIENT_CHARACTERISTICS",
    "parameters" : {
      "successCount" : 0,
      "minimumRequired" : 1,
      "ruleCount" : 2
    }
  } ],
  "messages" : [ "Password must contain 1 or more uppercase letters.", "Password must contain 1 or more digits or symbols." ]
}, {
  "type" : "ORACLE",
  "valid" : false,
  "entropy" : 28.0,
  "details" : [ {
    "errorCode" : "INSUFFICIENT_UPPERCASE",
    "parameters" : {
      "minimumRequired" : 1,
      "matchingCharacterCount" : 0,
      "validCharacters" : "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
      "matchingCharacters" : ""
    }
  }, {
    "errorCode" : "INSUFFICIENT_CHARACTERISTICS",
    "parameters" : {
      "successCount" : 0,
      "minimumRequired" : 1,
      "ruleCount" : 2
    }
  } ],
  "messages" : [ "Password must contain 1 or more uppercase letters.", "Password must contain 1 or more digits or symbols." ]
} ]

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: 1; mode=block
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

Returns the password validation rules.

Authorization

HTTP Auth is not required.

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

type

Object

true

Of the desired rule set.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 865

[ {
  "type" : "PID",
  "minimumLength" : 12,
  "maximumLength" : 64,
  "allowedCharacters" : " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~",
  "dictionaryCheck" : true,
  "usernameCheck" : true,
  "historyCheck" : true,
  "illegalSequences" : [ {
    "length" : 5,
    "type" : "Alphabetical"
  }, {
    "length" : 5,
    "type" : "USQwerty"
  }, {
    "length" : 5,
    "type" : "RepeatCharacter"
  } ],
  "illegalCharacters" : [ ],
  "whitespaceCharacters" : [ {
    "chars" : " ",
    "match" : "StartsWith"
  }, {
    "chars" : " ",
    "match" : "EndsWith"
  } ],
  "lengthRequirements" : {
    "[0,20)" : [ {
      "number" : 1,
      "types" : [ "LowerCase" ]
    }, {
      "number" : 1,
      "types" : [ "UpperCase" ]
    }, {
      "number" : 1,
      "types" : [ "Special", "Digit" ]
    } ]
  }
} ]

Person LDAP Search API

Fuzzy

GET /v1/persons/ldap/fuzzysearch

Performs a fuzzy LDAP search.

Authorization

HTTP Auth is not required.

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

query

String

false

To search against the template.

attr

Array[String]

true

Attributes to return.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 157

[ {
  "dn" : "uid=1111,ou=people,dc=vt,dc=edu",
  "givenName" : [ "Michael" ]
}, {
  "dn" : "uid=1112,ou=people,dc=vt,dc=edu",
  "givenName" : [ "Mark" ]
} ]

Search

GET /v1/persons/ldap/search

Performs an LDAP search.

Authorization

HTTP Auth is not required.

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

filter

String

false

To execute against the ldap.

attr

Array[String]

true

Attributes to return.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

[ {
  "dn" : "uid=1113,ou=people,dc=vt,dc=edu",
  "sn" : [ "Rock" ]
}, {
  "dn" : "uid=1114,ou=people,dc=vt,dc=edu",
  "sn" : [ "Slate" ]
} ]

Person Resource API

Delete

DELETE /v2/persons/{uid:[0-9]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of person.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

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: 1; mode=block
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=20004635), User(ID=20004637)]"
}

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 ].

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

uusid

String

false

Service unique identifier; follows requirements for ED account usernames.

expires

String

false

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

administrator

Object

false

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

contact

Object

true

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

protocol

String

true

Optional service protocol; defaults to Protocol#LDAP.

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

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/services/waw
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-z][a-z0-9._-]+}

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

Parameter

Type

Optional

Description

uusid

String

false

Service unique string identifier.

Query parameters

Parameter

Type

Optional

Description

with

Array[String]

true

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 985

{
  "uusid" : "iota",
  "displayName" : null,
  "description" : null,
  "creationDate" : "2024-04-05T19:54:22-04:00",
  "modificationDate" : null,
  "expirationDate" : null,
  "accountState" : "ACTIVE",
  "clientId" : "5e050a23-8c4f-10ac-83ce-000ef64390b3",
  "devTeam" : null,
  "protocol" : null,
  "integrationContext" : "BASE",
  "audiences" : [ ],
  "consent" : true,
  "metadataUrl" : null,
  "entitlements" : [ "middleware:ed/rest/services" ],
  "targetedGroups" : [ ],
  "serviceDns" : [ ],
  "viewablePersonAttributes" : [ ],
  "administrators" : [ ],
  "authorizedPersonaTypes" : [ "High" ],
  "certificates" : [ ],
  "keys" : [ ],
  "contacts" : [ ],
  "endpoints" : [ ],
  "identifiers" : [ {
    "id" : "5e050a23-8c4f-10ac-83ce-000ef64390b3",
    "type" : "clientId"
  } ],
  "notes" : [ ],
  "secrets" : [ ],
  "viewers" : [ ],
  "samlConfig" : {
    "nameIdFormat" : null,
    "signAssertions" : null,
    "signAuthnRequests" : null,
    "disableEncryption" : null
  }
}

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Query

GET /v1/services

Fetches a collection of service resources based on query terms. Supported query terms:

client_id - OAuth2 client identifier
crafter - created date after
crbefore - created date before
devteam - developer team name
entity_id - SAML entity ID
readable_attribute - attribute service can access/li>
uusid - unique identifier
administrator - subject in administrator role
contact - subject in contact role (deprecated)
manager - subject in manager role

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

No parameters.

Query parameters

Supports standard paging query parameters.

Parameter

Type

Optional

Description

params

Object

false

All request parameters, includes optional pagination parameters.

with

Array[String]

true

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

Response fields

No response body.

Example request

$ curl 'https://api.middleware.vt.edu/v1/services?client_id=9b8ee943-8c52-10ac-83d7-000ef64390b3' -i -X GET

Example 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: 1; mode=block
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: 510

[ {
  "uusid" : "aleph",
  "displayName" : null,
  "description" : null,
  "creationDate" : "2024-04-05T19:54:36-04:00",
  "modificationDate" : null,
  "expirationDate" : null,
  "accountState" : "ACTIVE",
  "clientId" : "9b8ee943-8c52-10ac-83d7-000ef64390b3",
  "devTeam" : null,
  "protocol" : null,
  "integrationContext" : "BASE",
  "audiences" : [ ],
  "consent" : true,
  "metadataUrl" : null,
  "entitlements" : [ ],
  "targetedGroups" : [ ],
  "serviceDns" : [ ],
  "viewablePersonAttributes" : [ ]
} ]

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Add Relation

POST /v1/services/{uusid:[a-z][a-z0-9._-]+}/{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

Parameter

Type

Optional

Description

uusid

String

false

ID of service to update.

role

String

false

Role to add members to.

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

Query parameters

Parameter

Type

Optional

Description

kind

String

false

Kind of member to add.

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

String

false

Unique identifier of member to add.

expiration

String

true

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

Response fields

No response body.

Example request

$ curl 'https://api.middleware.vt.edu/v1/services/alpha/administrators' -i -X POST \
    -d 'id=alice&kind=person&expiration=2024-05-05T19%3A54%3A34.174526-04%3A00'

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/services/alpha/administrators/alice
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Remove Relation

DELETE /v1/services/{uusid:[a-z][a-z0-9._-]+}/{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

Parameter

Type

Optional

Description

uusid

String

false

ID of service to update.

role

String

false

Role to remove member from.

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

String

false

ID of member to remove from role.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/services/alpha/administrators/test.middleware-group
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Shelve

POST /v2/services/{uusid:[a-z][a-z0-9._-]+}/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

Parameter

Type

Optional

Description

uusid

String

false

Service account to shelve.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Add Viewable Person Attributes

POST /v1/services/{uusid:[a-z][a-z0-9._-]+}/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

Parameter

Type

Optional

Description

uusid

String

false

ID of service to update.

Query parameters

Parameter Type Optional Description

attribute

Object

false

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

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/services/delta
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-z][a-z0-9._-]+}/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

Parameter

Type

Optional

Description

uusid

String

false

ID of service to update.

attribute

String

false

Viewable person attribute.

Must be one of [{"oid":"1.3.6.1.4.1.6760.6.1.1","label":"Academic Level","description":"The degree level currently being sought by a person","singleValued":true,"replicationOnly":false,"name":"academicLevel"}, {"oid":"1.3.6.1.4.1.6760.6.1.154","label":"Account Checkup Date","description":"Last date where account checkup was performed","singleValued":true,"replicationOnly":false,"name":"accountCheckupDate"}, {"oid":"1.3.6.1.4.1.6760.6.1.109","label":"Account Creation Date","description":"The date the person’s account was created","singleValued":true,"replicationOnly":false,"name":"accountCreationDate"}, {"oid":"1.3.6.1.4.1.6760.6.1.110","label":"Account Expiration Date","description":"The date the person’s account will expire","singleValued":true,"replicationOnly":false,"name":"accountExpirationDate"}, {"oid":"1.3.6.1.4.1.6760.6.1.111","label":"Account Shelve Date","description":"The date the person’s account will be moved to the SHELVED state","singleValued":true,"replicationOnly":false,"name":"accountShelveDate"}, {"oid":"","label":"Account Sponsor","description":"The account username of the person that sponsored the creation of this person’s account.","singleValued":true,"replicationOnly":false,"name":"accountSponsor"}, {"oid":"1.3.6.1.4.1.6760.6.1.73","label":"Account State","description":"The current authentication state of the person’s account","singleValued":true,"replicationOnly":false,"name":"accountState"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.7","label":"Account Transition","description":"The next transitions the account will undergo in its lifecycle","singleValued":false,"replicationOnly":true,"name":"accountTransition"}, {"oid":"1.3.6.1.4.1.6760.6.1.121","label":"Authentication Identifier","description":"The authentication identifier(s)","singleValued":false,"replicationOnly":false,"name":"authId"}, {"oid":"1.3.6.1.4.1.6760.6.1.93","label":"Banner Name","description":"The name of this person as it appears in the Banner spriden table","singleValued":true,"replicationOnly":false,"name":"bannerName"}, {"oid":"1.3.6.1.4.1.6760.6.1.85","label":"Banner PIDM","description":"The 8 digit Banner PIDM number for this person","singleValued":true,"replicationOnly":false,"name":"bannerPIDM"}, {"oid":"2.5.4.6","label":"Country","description":"The two letter abbreviation for the country that this address is in (ISO 3166 code)","singleValued":true,"replicationOnly":false,"name":"c"}, {"oid":"1.3.6.1.4.1.6760.6.1.5","label":"Campus","description":"The name of the campus this person is currently affiliated with. For instance the campus a student is attending, or the campus at which a staff member works","singleValued":true,"replicationOnly":false,"name":"campus"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.145","label":"Channel","description":"The numeric replication channel that is assigned to this entity when it replicates","singleValued":true,"replicationOnly":true,"name":"channel"}, {"oid":"1.3.6.1.4.1.6760.6.1.23","label":"City","description":"The city the street or post office box is in","singleValued":true,"replicationOnly":false,"name":"city"}, {"oid":"1.3.6.1.4.1.6760.6.1.112","label":"Class Level","description":"The Banner class level","singleValued":true,"replicationOnly":false,"name":"classLevel"}, {"oid":"1.3.6.1.4.1.6760.6.1.113","label":"Class Level Code","description":"The Banner class level code","singleValued":true,"replicationOnly":false,"name":"classLevelCode"}, {"oid":"2.5.4.3","label":"Common Name","description":"Preferred name of a person to be used when a full name is needed","singleValued":false,"replicationOnly":false,"name":"cn"}, {"oid":"TODO","label":"Coalition ID","description":"Uniquely identifies a college applicant in the Coalition for College system","singleValued":true,"replicationOnly":false,"name":"coalitionID"}, {"oid":"TODO","label":"College","description":"A student’s college corresponding to the academic major","singleValued":false,"replicationOnly":false,"name":"college"}, {"oid":"1.3.6.1.4.1.6760.6.1.7","label":"Person Creation Date","description":"The date the person was added to the directory","singleValued":true,"replicationOnly":false,"name":"creationDate"}, {"oid":"1.3.6.1.4.1.6760.6.1.53","label":"Birth Date","description":"A person’s date of birth","singleValued":false,"replicationOnly":false,"name":"dateOfBirth"}, {"oid":"1.3.6.1.4.1.6760.6.1.132","label":"Deceased Flag","description":"Whether this person is deceased","singleValued":true,"replicationOnly":false,"name":"deceasedFlag"}, {"oid":"1.3.6.1.4.1.6760.6.1.74","label":"Degree Type","description":"The type of degree a student is seeking","singleValued":true,"replicationOnly":false,"name":"degreeType"}, {"oid":"1.3.6.1.4.1.6760.6.1.65","label":"Department","description":"The home department this person works in on campus","singleValued":true,"replicationOnly":false,"name":"department"}, {"oid":"2.16.840.1.113730.3.1.2","label":"Department Number","description":"The organization code of the department this person works in on campus","singleValued":false,"replicationOnly":false,"name":"departmentNumber"}, {"oid":"2.16.840.1.113730.3.1.241","label":"Display Name","description":"Preferred name of a person to be used when a full name is needed","singleValued":true,"replicationOnly":false,"name":"displayName"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.1","label":"eduPerson Affiliation","description":"Specifies the person’s relationship(s) to the institution in broad categories such as student, faculty, staff,\nalum, etc.","singleValued":false,"replicationOnly":false,"name":"eduPersonAffiliation"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.11","label":"eduPerson Assurance","description":"Set of URIs that assert compliance with specific standards for identity assurance.","singleValued":false,"replicationOnly":false,"name":"eduPersonAssurance"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.7","label":"eduPerson Entitlement","description":"URI (either URN or URL) that indicates a set of rights to specific resources.","singleValued":false,"replicationOnly":false,"name":"eduPersonEntitlement"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.2","label":"eduPerson Nickname","description":"Person’s nickname, or the informal name by which they are accustomed to be hailed.","singleValued":false,"replicationOnly":false,"name":"eduPersonNickname"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.16","label":"eduPerson ORCID","description":"ORCID iDs are persistent digital identifiers for individual researchers. Their primary purpose is to\nunambiguously and definitively link them with their scholarly work products. ORCID iDs are assigned,\nmanaged and maintained by the ORCID organization.","singleValued":false,"replicationOnly":false,"name":"eduPersonOrcid"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.3","label":"eduPerson Organization Distinguished Name","description":"The distinguished name (DN) of the directory entry representing the institution with which the person is\nassociated.","singleValued":true,"replicationOnly":false,"name":"eduPersonOrgDN"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.4","label":"eduPerson Organizational Unit Distinguished Name","description":"The distinguished name(s) (DN) of the directory entries representing the person’s Organizational Unit(s).\nMay be multivalued, as for example, in the case of a faculty member with appointments in multiple departments or\na person who is a student in one department and an employee in another.","singleValued":false,"replicationOnly":false,"name":"eduPersonOrgUnitDN"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.5","label":"eduPerson Primary Affiliation","description":"Specifies the person’s primary relationship to the institution in broad categories such as student, faculty,\nstaff, alum, etc. (See controlled vocabulary).","singleValued":true,"replicationOnly":false,"name":"eduPersonPrimaryAffiliation"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.8","label":"eduPerson Primary Organizational Unit Distinguished Name","description":"The distinguished name (DN) of the directory entry representing the person’s primary Organizational Unit(s).","singleValued":true,"replicationOnly":false,"name":"eduPersonPrimaryOrgUnitDN"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.6","label":"eduPerson Principal Name","description":"A scoped identifier for a person defined as \"username@vt.edu\" for Virginia Tech accounts.","singleValued":true,"replicationOnly":false,"name":"eduPersonPrincipalName"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.9","label":"eduPerson Scoped Affiliation","description":"Specifies the person’s affiliation within a particular security domain in broad categories such as student@vt.edu,nfaculty@vt.edu, staff@vt.edu, alum@vt.edu, etc.","singleValued":false,"replicationOnly":false,"name":"eduPersonScopedAffiliation"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.10","label":"eduPerson Targeted ID","description":"A persistent, non-reassigned, opaque identifier for a principal.","singleValued":false,"replicationOnly":false,"name":"eduPersonTargetedID"}, {"oid":"1.3.6.1.4.1.5923.1.1.1.13","label":"eduPerson Unique ID","description":"A long-lived, non re-assignable, omnidirectional identifier suitable for use as a principal identifier by\nauthentication providers or as a unique external key by applications.","singleValued":false,"replicationOnly":false,"name":"eduPersonUniqueId"}, {"oid":"1.3.6.1.4.1.6760.6.1.155","label":"Employee Confidentiality Flag","description":"Whether this employee is confidential","singleValued":true,"replicationOnly":false,"name":"employeeConfidential"}, {"oid":"1.3.6.1.4.1.6760.6.1.123","label":"Employee Off-Campus Flag","description":"Whether an employee is off campus or not","singleValued":true,"replicationOnly":false,"name":"employeeOffCampus"}, {"oid":"2.5.4.23","label":"Fax Number","description":"Fax (facsimile) telephone number","singleValued":true,"replicationOnly":false,"name":"facsimileTelephoneNumber"}, {"oid":"1.3.6.1.4.1.6760.6.1.122","label":"Gender","description":"The gender of the person","singleValued":true,"replicationOnly":false,"name":"gender"}, {"oid":"1.3.6.1.1.1.1.1","label":"GID Number","description":"An integer uniquely identifying a POSIX group in an administrative domain","singleValued":true,"replicationOnly":false,"name":"gidNumber"}, {"oid":"2.5.4.42","label":"First Name","description":"The person’s given name(s). A \"given name\" is commonly called a \"first name\", but in some cultures like Chinese\nthe given name is written last.","singleValued":false,"replicationOnly":false,"name":"givenName"}, {"oid":"1.3.6.1.4.1.6760.6.1.161","label":"Google Mailbox","description":"The address of the person’s Google Mailbox on the VT Google mail domain, which is presently defined as\nusername + \"@g.mail.vt.edu\".","singleValued":true,"replicationOnly":false,"name":"googleMailbox"}, {"oid":"1.3.6.1.4.1.6760.6.1.101","label":"Group Membership DNs","description":"A list of the group distinguished names (DNs) this person is a member of","singleValued":false,"replicationOnly":false,"name":"groupMembership"}, {"oid":"1.3.6.1.4.1.6760.6.1.134","label":"Group Membership","description":"A list of the groups this person is a member of","singleValued":false,"replicationOnly":false,"name":"groupMembershipUugid"}, {"oid":"1.3.6.1.4.1.6760.6.1.120","label":"Guest ID","description":"The guest identifier for authentication","singleValued":true,"replicationOnly":false,"name":"guestId"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.165","label":"Hokies Password","description":"The password of the person’s Active Directory account in the HOKIES domain","singleValued":false,"replicationOnly":true,"name":"hokiesPassword"}, {"oid":"1.3.6.1.1.1.1.3","label":"Home Directory","description":"The absolute path to the home directory for POSIX accounts","singleValued":true,"replicationOnly":false,"name":"homeDirectory"}, {"oid":"1.3.6.1.4.1.6760.6.1.106","label":"Home Fax Number","description":"This should be the fax number associated with the address whose address type is home.","singleValued":false,"replicationOnly":false,"name":"homeFax"}, {"oid":"1.3.6.1.4.1.6760.6.1.102","label":"Home Mobile Number","description":"The mobile phone number of the person associated with the address whose address type is home.","singleValued":false,"replicationOnly":false,"name":"homeMobile"}, {"oid":"1.3.6.1.4.1.6760.6.1.104","label":"Home Pager Number","description":"The pager number of the person associated with the address whose address type is home.","singleValued":false,"replicationOnly":false,"name":"homePager"}, {"oid":"0.9.2342.19200300.100.1.20","label":"Home Phone Number","description":"The phone number of the person associated with the address whose address type is home.","singleValued":false,"replicationOnly":false,"name":"homePhone"}, {"oid":"0.9.2342.19200300.100.1.39","label":"Home Postal Address","description":"The home postal address for this person","singleValued":true,"replicationOnly":false,"name":"homePostalAddress"}, {"oid":"1.3.6.1.4.1.6760.6.1.10","label":"Instant Messaging ID","description":"A list of a person’s instant messaging Ids","singleValued":false,"replicationOnly":false,"name":"instantMessagingID"}, {"oid":"1.3.6.1.4.1.6760.6.1.88","label":"Member Of","description":"A list of the groups, identified by the groups DN, this person is a member of","singleValued":false,"replicationOnly":false,"name":"isMemberOf"}, {"oid":"2.5.4.7","label":"City","description":"Locality/city where the person resides","singleValued":true,"replicationOnly":false,"name":"l"}, {"oid":"1.3.6.1.4.1.250.1.57","label":"Labeled URI","description":"Uniform Resource Identifier (URI) with optional label. This attribute is typically used to publish Web sites\nand other personal Internet addresses that the person wishes to make publicly available.","singleValued":false,"replicationOnly":false,"name":"labeledURI"}, {"oid":"1.3.6.1.4.1.6760.6.1.75","label":"Last Enrollment Term","description":"Human readable form of the last academic term a student was enrolled in","singleValued":true,"replicationOnly":false,"name":"lastEnrollmentTerm"}, {"oid":"1.3.6.1.4.1.6760.6.1.97","label":"Last Enrollment Term Code","description":"The last academic term code a student was enrolled in","singleValued":true,"replicationOnly":false,"name":"lastEnrollmentTermCode"}, {"oid":"1.3.6.1.4.1.6760.6.1.107","label":"Local Fax Number","description":"The fax number associated with the address whose address type is local.","singleValued":false,"replicationOnly":false,"name":"localFax"}, {"oid":"1.3.6.1.4.1.6760.6.1.103","label":"Local Mobile Number","description":"The mobile phone number of the person associated with the address whose address type is local.","singleValued":false,"replicationOnly":false,"name":"localMobile"}, {"oid":"1.3.6.1.4.1.6760.6.1.105","label":"Local Pager Number","description":"The pager number of the person associated associated with the address whose address type is local.","singleValued":false,"replicationOnly":false,"name":"localPager"}, {"oid":"1.3.6.1.4.1.6760.6.1.80","label":"Local Phone Number","description":"The local phone number of this person","singleValued":false,"replicationOnly":false,"name":"localPhone"}, {"oid":"1.3.6.1.4.1.6760.6.1.81","label":"Local Postal Address","description":"The local postal address for this person","singleValued":true,"replicationOnly":false,"name":"localPostalAddress"}, {"oid":"0.9.2342.19200300.100.1.3","label":"Email Address","description":"All known email addresses for the person","singleValued":false,"replicationOnly":false,"name":"mail"}, {"oid":"1.3.6.1.4.1.6760.6.1.96","label":"Email Account","description":"The name of the person’s email account in the mail system","singleValued":true,"replicationOnly":false,"name":"mailAccount"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.173","label":"Email Account State","description":"The state of the person’s email account","singleValued":true,"replicationOnly":true,"name":"mailAccountState"}, {"oid":"1.3.6.1.4.1.6760.6.1.95","label":"Email Alias","description":"These are the e-mail alias(es) of a person","singleValued":false,"replicationOnly":false,"name":"mailAlias"}, {"oid":"1.3.6.1.4.1.6760.6.1.148","label":"Auxiliary Email Account","description":"These the auxiliary e-mail accounts of a person","singleValued":false,"replicationOnly":false,"name":"mailAuxiliaryAccount"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.60","label":"Display Email Address","description":"Needed for replication","singleValued":false,"replicationOnly":true,"name":"mailDisplayAddress"}, {"oid":"1.3.6.1.4.1.6760.6.1.127","label":"External Email Address","description":"A person’s external email address","singleValued":false,"replicationOnly":false,"name":"mailExternalAddress"}, {"oid":"1.3.6.1.4.1.6760.6.1.8","label":"Email Forwarding Address","description":"A person’s email forwarding address","singleValued":false,"replicationOnly":false,"name":"mailForwardingAddress"}, {"oid":"1.3.6.1.4.1.6760.6.1.91","label":"Preferred Email Address","description":"A person’s preferred email address","singleValued":true,"replicationOnly":false,"name":"mailPreferredAddress"}, {"oid":"1.3.6.1.4.1.6760.6.1.25","label":"Mail Stop","description":"Used for internal (on-campus) mail routing information. Do not use for Post Office Box information.","singleValued":true,"replicationOnly":false,"name":"mailStop"}, {"oid":"1.3.6.1.4.1.6760.6.1.76","label":"Academic Major","description":"The academic major of this person","singleValued":false,"replicationOnly":false,"name":"major"}, {"oid":"1.3.6.1.4.1.6760.6.1.92","label":"Academic Major Code","description":"The academic major code of this person","singleValued":false,"replicationOnly":false,"name":"majorCode"}, {"oid":"1.3.6.1.4.1.6760.6.1.64","label":"Middle Name","description":"The middle name(s) of a person","singleValued":false,"replicationOnly":false,"name":"middleName"}, {"oid":"0.9.2342.19200300.100.1.41","label":"Mobile Phone Number","description":"The person’s mobile phone number","singleValued":false,"replicationOnly":false,"name":"mobile"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.69","label":"Modification Date","description":"The last date where this person’s record was changed","singleValued":false,"replicationOnly":true,"name":"modificationDate"}, {"oid":"1.3.6.1.4.1.6760.6.1.83","label":"Network Password","description":"The network password","singleValued":true,"replicationOnly":false,"name":"networkPassword"}, {"oid":"1.3.6.1.4.1.6760.6.1.77","label":"Next Enrollment Term","description":"The next academic term a student is enrolled in","singleValued":true,"replicationOnly":false,"name":"nextEnrollmentTerm"}, {"oid":"1.3.6.1.4.1.6760.6.1.98","label":"Next Enrollment Term Code","description":"The human readable form of the next academic term a student is enrolled in","singleValued":true,"replicationOnly":false,"name":"nextEnrollmentTermCode"}, {"oid":"2.5.4.0","label":"Object Class","description":"The LDAP object classes to which this person belongs","singleValued":false,"replicationOnly":false,"name":"objectClass"}, {"oid":"2.5.4.11","label":"Organizational Unit","description":"RFC2256: organizational unit this object belongs to","singleValued":false,"replicationOnly":false,"name":"ou"}, {"oid":"0.9.2342.19200300.100.1.42","label":"Pager Number","description":"Pager device telephone number","singleValued":true,"replicationOnly":false,"name":"pager"}, {"oid":"1.3.6.1.4.1.6760.6.1.167","label":"Pairwise ID","description":"A long-lived, non-re-assignable, uni-directional identifier suitable as a unique external key specific to\nparticular applications; it is specified as part of SAML V2.0 Subject Identifier Attributes Profile Version 1.0.\nIts value for a given subject depends on the relying party to whom it is given, preventing unrelated systems\nfrom using it as a basis for correlation.","singleValued":true,"replicationOnly":false,"name":"pairwiseId"}, {"oid":"1.3.6.1.4.1.6760.6.1.147","label":"Password Change Date","description":"The date the password was changed","singleValued":false,"replicationOnly":false,"name":"passwordChangeDate"}, {"oid":"1.3.6.1.4.1.6760.6.1.133","label":"Password Expiration Date","description":"The date the password will expire","singleValued":true,"replicationOnly":false,"name":"passwordExpirationDate"}, {"oid":"1.3.6.1.4.1.6760.6.1.94","label":"Password State","description":"Indicates the current state of a person’s password, which may be either active or expired","singleValued":true,"replicationOnly":false,"name":"passwordState"}, {"oid":"1.3.6.1.4.1.6760.6.1.108","label":"Person Type","description":"The type of person.","singleValued":true,"replicationOnly":false,"name":"personType"}, {"oid":"2.5.4.16","label":"Postal Address","description":"The postal address for this person","singleValued":true,"replicationOnly":false,"name":"postalAddress"}, {"oid":"2.5.4.17","label":"Postal Code","description":"Address ZIP code or other postal code for non-US addresses","singleValued":true,"replicationOnly":false,"name":"postalCode"}, {"oid":"2.5.4.18","label":"Post Offix Box","description":"The post office box part of the address","singleValued":true,"replicationOnly":false,"name":"postOfficeBox"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.84","label":"Preferred First Name","description":"The person’s preferred given name","singleValued":false,"replicationOnly":true,"name":"preferredFirstName"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.85","label":"Preferred Last Name","description":"The person’s preferred surname","singleValued":false,"replicationOnly":true,"name":"preferredLastName"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.86","label":"Preferred Middle Name","description":"The person’s preferred middle name","singleValued":false,"replicationOnly":true,"name":"preferredMiddleName"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.87","label":"Preferred Name Suffix","description":"The person’s preferred name suffix (i.e. Jr, III)","singleValued":false,"replicationOnly":true,"name":"preferredSuffix"}, {"oid":"1.3.6.1.4.1.6760.6.1.159","label":"Public Directory Attributes","description":"The public directory attributes","singleValued":false,"replicationOnly":false,"name":"publicDirectoryAttributes"}, {"oid":"","label":"Self-Reported Phone Number","description":"Phone number that a person has reported without any verification process","singleValued":true,"replicationOnly":false,"name":"selfPhone"}, {"oid":"","label":"Self-Reported Postal Address","description":"Address that a person has reported without any verification process","singleValued":true,"replicationOnly":false,"name":"selfPostalAddress"}, {"oid":"1.3.6.1.4.1.6760.6.1.158","label":"Public Directory Display Flag","description":"Whether to show in the public directory","singleValued":true,"replicationOnly":false,"name":"showInPublicDirectory"}, {"oid":"2.5.4.4","label":"Last Name","description":"The person’s surname(s). A surname is commonly called a \"last name\", but in some cultures like Chinese the\nsurname is written first.","singleValued":false,"replicationOnly":false,"name":"sn"}, {"oid":"2.5.4.8","label":"State","description":"The full name of the state or province part of the address","singleValued":false,"replicationOnly":false,"name":"st"}, {"oid":"2.5.4.9","label":"Street Address","description":"The first line of a person’s street address. Normally this would be the house number and road they live on","singleValued":true,"replicationOnly":false,"name":"street"}, {"oid":"1.3.6.1.4.1.6760.6.1.29","label":"Street Address (Line 2)","description":"Supplementary address information that would go on the second line of an envelope.","singleValued":true,"replicationOnly":false,"name":"street1"}, {"oid":"1.3.6.1.4.1.6760.6.1.30","label":"Street Address (Line 3)","description":"Supplementary address information that would go on the third line of an envelope.","singleValued":true,"replicationOnly":false,"name":"street2"}, {"oid":"1.3.6.1.4.1.6760.6.1.156","label":"Student Confidentiality Flag","description":"Whether this student is confidential","singleValued":true,"replicationOnly":false,"name":"studentConfidential"}, {"oid":"1.3.6.1.4.1.6760.6.1.129","label":"Student Academic Level Code","description":"The current student level code","singleValued":true,"replicationOnly":false,"name":"studentLevelCode"}, {"oid":"1.3.6.1.4.1.6760.6.1.168","label":"Subject ID","description":"A long-lived, non-re-assignable, uni-directional identifier suitable as a unique external key specific to\nparticular applications; it is specified as part of SAML V2.0 Subject Identifier Attributes Profile Version 1.0.\nIts value for a given subject depends on the relying party to whom it is given, preventing unrelated systems from\nusing it as a basis for correlation. This attribute is commonly implemented as follows:\nsubjectId = uidNumber + \"@vt.edu\"","singleValued":true,"replicationOnly":false,"name":"subjectId"}, {"oid":"1.3.6.1.4.1.6760.6.5.1.182","label":"Suppress All","description":"Whether the person has opted to hide all personal demographic data elements in the public directory","singleValued":true,"replicationOnly":true,"name":"suppressAll"}, {"oid":"1.3.6.1.4.1.6760.6.1.99","label":"Suppress Display","description":"Whether this person’s entire record should be suppressed from public view","singleValued":true,"replicationOnly":false,"name":"suppressDisplay"}, {"oid":"1.3.6.1.4.1.6760.6.1.118","label":"Suppress Employee","description":"Whether this employee is suppressed","singleValued":true,"replicationOnly":false,"name":"suppressEmployeeDisplay"}, {"oid":"1.3.6.1.4.1.6760.6.1.17","label":"Suppressed Attribute","description":"The user attributes a person wants to suppress from public display","singleValued":false,"replicationOnly":false,"name":"suppressedAttribute"}, {"oid":"1.3.6.1.4.1.6760.6.1.162","label":"Targeted Group Membership","description":"Works in concert with the targetedGroups attribute on a service. When an application is authenticating to a\nservice, either via SSO or via the directory with an authorization context of that service, if the service has\na non-empty targetedGroups attribute, targetedMembership is defined as a filter to limit groupMembershipUugid\nvalues to those that start with any of the values defined on the service. If the targetedGroups attribute is\nempty or the authorization context of the query does not resolve to a service, then targetedMembership values\nare not filtered and are equivalent to groupMembershipUugid attribute values.","singleValued":false,"replicationOnly":false,"name":"targetedMembership"}, {"oid":"1.3.6.1.4.1.6760.6.1.102","label":"Phone Number","description":"Primary phone number","singleValued":false,"replicationOnly":false,"name":"telephoneNumber"}, {"oid":"2.5.4.12","label":"Job Title","description":"The employee’s job title","singleValued":true,"replicationOnly":false,"name":"title"}, {"oid":"1.3.6.1.4.1.6760.6.1.126","label":"Banner UDC Identifier","description":"The Banner UDC identifier that uniquely identifies a subject across systems that integrate tightly with Banner.","singleValued":true,"replicationOnly":false,"name":"udcIdentifier"}, {"oid":"0.9.2342.19200300.100.1.1","label":"Registry Unique ID","description":"A unique number that identifies a person that will never change","singleValued":true,"replicationOnly":false,"name":"uid"}, {"oid":"1.3.6.1.1.1.1.0","label":"UID Number","description":"An integer uniquely identifying a POSIX user in an administrative domain","singleValued":true,"replicationOnly":false,"name":"uidNumber"}, {"oid":"1.3.6.1.4.1.6760.6.1.78","label":"Undergraduate Level","description":"The current grade level of an undergraduate student, e.g. Freshman, Sophomore, etc","singleValued":true,"replicationOnly":false,"name":"undergraduateLevel"}, {"oid":"2.5.4.36","label":"User Certificate","description":"The person’s PEM-encoded X.509 certificates for sending signed and encrypted messages","singleValued":false,"replicationOnly":false,"name":"userCertificate"}, {"oid":"1.3.6.1.4.1.6760.6.1.153","label":"Username","description":"The person’s primary account username","singleValued":false,"replicationOnly":false,"name":"username"}, {"oid":"2.5.4.35","label":"Account Password","description":"The person’s account password","singleValued":false,"replicationOnly":false,"name":"userPassword"}, {"oid":"2.16.840.1.113730.3.1.40","label":"User S/MIME Certificate","description":"The person’s S/MIME-encoded certificates for sending signed and encrypted messages","singleValued":false,"replicationOnly":false,"name":"userSMIMECertificate"}, {"oid":"1.3.6.1.4.1.6760.6.1.19","label":"PID","description":"The person’s primary account username","singleValued":true,"replicationOnly":false,"name":"uupid"}, {"oid":"1.3.6.1.4.1.6760.6.1.125","label":"Virginia Tech Affiliation","description":"Specifies the person’s relationships to Virginia Tech in specific categories such as VT-STUDENT, VT-FACULTY, VT-STAFF, VT-ALUM, etc","singleValued":false,"replicationOnly":false,"name":"virginiaTechAffiliation"}, {"oid":"1.3.6.1.4.1.6760.6.1.87","label":"Virginia Tech ID","description":"The 9 digit Virginia Tech ID number from Banner, sometimes known as the Banner ID number","singleValued":true,"replicationOnly":false,"name":"virginiaTechID"}].

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/services/foxtrot
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Add Endpoint

POST /v1/services/{uusid:[a-z][a-z0-9._-]+}/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

Parameter

Type

Optional

Description

uusid

String

false

ID of service to update.

Query parameters

Parameter Type Optional Description

protocol

String

false

Endpoint communication protocol.

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

location

Object

false

Endpoint location URI.

binding

String

true

Binding; required when protocol is SAML2.

kind

String

true

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

Response fields

No response body.

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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/services/heh
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-z][a-z0-9._-]+}/endpoints/{id:[0-9]+}

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

Parameter

Type

Optional

Description

uusid

String

false

ID of service to update.

Integer

false

Unique ID of endpoint to remove.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/services/het
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-z][a-z0-9._-]+}/password/{action:add|remove}

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

Parameter Type Optional Description

uusid

String

false

ID of service to update.

action

String

false

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.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 43
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

{
  "password" : "X2K40BoAffcRQrwp8lFY75"
}

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Add Certificate

POST /v1/services/{uusid:[a-z][a-z0-9._-]+}/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

Parameter

Type

Optional

Description

uusid

String

false

ID of the service to update.

Query parameters

Parameter

Type

Optional

Description

pem

String

false

PEM encoded X.509 certificate.

use

String

true

Optional usage criteria.

Response fields

No response body.

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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v1/services/middleware-test
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[a-z][a-z0-9._-]+}/certificates/{serial:[0-9]+}

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

Parameter

Type

Optional

Description

uusid

String

false

ID of the service to update.

serial

String

false

Serial number in decimal representation.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/services/middleware-test
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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"
}

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 ].

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

scope

String

false

Purpose of token.

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

type

String

true

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

String

true

OTP recipient email address.

sms

Integer

true

OTP recipient mobile phone number.

voice

String

true

OTP recipient phone number.

Response fields

No response body.

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

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: 1; mode=block
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

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: 1; mode=block
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

Parameter

Type

Optional

Description

String

false

Token identifier/handle.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 278

{
  "id" : "FpsLWEcf5YpMULQa91cq25x2Hqk",
  "expiration" : "2024-04-05T20:05:09-04:00",
  "scopes" : [ "PASSWORD_RESET" ],
  "metadata" : [ {
    "key" : "ed.token.otp",
    "value" : "013984"
  }, {
    "key" : "ed.token.recipient",
    "value" : "somebody@example.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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is 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 ].

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

code

String

false

OTP code.

String

true

Email address of OTP recipient.

phone

String

true

Phone number of OTP recipient.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 278

{
  "id" : "ebUmFcXbpJtBmHsTGfPpH33ZJ5c",
  "expiration" : "2024-04-05T20:05:09-04:00",
  "scopes" : [ "PASSWORD_RESET" ],
  "metadata" : [ {
    "key" : "ed.token.otp",
    "value" : "718359"
  }, {
    "key" : "ed.token.recipient",
    "value" : "somebody@example.com"
  } ]
}

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: 1; mode=block
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:[0-9]+}

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

Parameter

Type

Optional

Description

uid

String

false

UID of user to fetch.

Query parameters

Parameter

Type

Optional

Description

with

Array[String]

true

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

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 1307

{
  "uid" : 7100001,
  "personUid" : 7100002,
  "creationDate" : "2024-04-05T19:54:57-04:00",
  "pid" : "hammy",
  "mailPreferredAddress" : "kate@vt.edu",
  "type" : "VT",
  "sponsored" : false,
  "dateOfBirth" : "1959-01-01",
  "displayName" : "Kate Carver",
  "gender" : "Female",
  "virginiaTechId" : "905355555",
  "addresses" : [ ],
  "phones" : [ {
    "id" : 11,
    "displayName" : null,
    "number" : "1111111111",
    "country" : null,
    "type" : "CELLULAR"
  } ],
  "affiliations" : [ "VT-ACTIVE-MEMBER", "VT-EMPLOYEE", "VT-EMPLOYEE-STATE" ],
  "certificates" : [ ],
  "employeeData" : null,
  "identifiers" : [ {
    "id" : "905355555",
    "type" : "vtid"
  } ],
  "mailboxes" : [ "kate@vt.edu", "kateaux@vt.edu" ],
  "names" : [ {
    "first" : "Katherine",
    "middle" : null,
    "last" : "Carver",
    "prefix" : null,
    "suffix" : null,
    "type" : "BANNER"
  }, {
    "first" : "Kate",
    "middle" : null,
    "last" : "Carver",
    "prefix" : null,
    "suffix" : null,
    "type" : "PREFERRED"
  } ],
  "emails" : [ {
    "address" : "katy@gmail.com",
    "type" : "PRC"
  } ],
  "imids" : [ ],
  "uris" : [ ],
  "studentData" : null,
  "suppressAll" : true,
  "suppressDisplay" : true,
  "suppressions" : [ "postalAddress", "uupid" ],
  "suppressibleAttributes" : [ "uupid" ]
}

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: 1; mode=block
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:[0-9]+}/{property:[a-z]+}

Fetches a collection of subordinate resources of a user.

addresses
affiliations
certificates
externalEmailAddresses
identifiers
instantMessagingIds
mailboxes
names
phones
suppressions
websites

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

Parameter

Type

Optional

Description

uid

String

false

UID of user to fetch.

property

String

false

Sub-resource collection of the user to be fetched.

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

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 233

[ {
  "street1" : "123 Fluffington Way",
  "street2" : "Apt 3b",
  "street3" : "Box 1",
  "city" : "Blacksburg",
  "state" : "VA",
  "zip" : "24060",
  "country" : "US",
  "mailStop" : "1234",
  "poBox" : null,
  "type" : "LOCAL"
} ]

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: 1; mode=block
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. Supported query terms:

affiliation
appl - external email address of type APPLICANT_EMAIL
ext - external email address of any type
first - first name
last - last name
mail - mailbox primary or alias
person - associated person uid
phone - phone number/li>
pidm - Banner PIDM/li>
sponsor - sponsor of the service account/li>
uupid - account identifier, username or email
vtid - Virginia Tech ID

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

No parameters.

Query parameters

Supports standard paging query parameters.

Parameter

Type

Optional

Description

params

Object

false

All request parameters, may include pagination parameters.

with

Array[String]

true

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

Response fields

No response body.

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

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: 1; mode=block
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: 109

[ {
  "uid" : 22222222,
  "personUid" : 20002095,
  "dateOfBirth" : "1941-04-05",
  "suppressAll" : false
} ]

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is 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 ].

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

pidm

String

false

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

first

String

false

Person first name.

last

String

false

Person middle name.

affiliation

Object

false

Set of user affiliations.

prefix

String

true

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

middle

String

true

Person middle name.

suffix

String

true

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

birth

Object

true

Birth date.

Response fields

No response body.

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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/20001984
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is 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 ].

Path parameters

No parameters.

Query parameters

Parameter

Type

Optional

Description

first

String

false

Person first name.

last

String

false

Person middle name.

affiliation

Object

false

Set of user affiliations.

prefix

String

true

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

middle

String

true

Person middle name.

suffix

String

true

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

Response fields

No response body.

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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/20001993
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Delete

DELETE /v2/users/{uid:[0-9]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/link/{personUid:[0-9]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user to link.

personUid

Integer

false

UID of person to associate with the user.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/20002177
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Add Certificate

POST /v2/users/{uid:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

Parameter

Type

Optional

Description

type

String

false

Type of certificate.

Must be one of [X509, SMIME].

cert

String

false

PEM-encoded certificate.

Response fields

No response body.

Example request

$ curl 'https://api.middleware.vt.edu/v2/users/20002001/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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/20002001/certificates/smime
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Remove Certificate

DELETE /v2/users/{uid:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

type

String

false

Type of certificate.

Must be one of [X509, SMIME].

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/20001567
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

Parameter

Type

Optional

Description

type

String

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

String

false

External email address to add.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/20002497/emails/dsp
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/emails/{typeCode:[a-z]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

typeCode

String

false

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

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

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/20002367
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

Parameter

Type

Optional

Description

type

String

false

Identifier type to add.

Must be one of [COAID, PIDM, UDCID, VTID].

String

false

Value (ID) of the new identifier.

Response fields

No response body.

Example request

$ curl 'https://api.middleware.vt.edu/v2/users/20002283/identifiers' -i -X POST \
    -d 'type=vtid&id=987654321'

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/20002283/identifiers/vtid
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 140

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

Remove Identifier

DELETE /v2/users/{uid:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

type

String

false

Identifier type to remove.

Must be one of [COAID, PIDM, UDCID, VTID].

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/20002326
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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 'pairwiseid'. Valid types: [ COAID, PIDM, UDCID, VTID ]"
}

Add Address

POST /v2/users/{uid:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

Parameter

Type

Optional

Description

type

String

false

Type of address.

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

state

String

true

State/province code.

unlisted

Boolean

true

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

Default value: 'false'.

street1

String

true

First part of street address.

street2

String

true

Second part of street address.

street3

String

true

Third part of street address.

pobox

String

true

Post office box.

city

String

true

City name.

zip

String

true

Postal code.

country

String

true

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

mailStop

String

true

MailStop (4 digit number).

Response fields

No response body.

Example request

$ curl 'https://api.middleware.vt.edu/v2/users/20001708/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

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/20001708/addresses/office
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Remove Address

DELETE /v2/users/{uid:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of the user.

type

String

false

Address type to remove.

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

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/20001648
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Update Address

PATCH /v2/users/{uid:[0-9]+}/addresses/{type:[a-z]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user whose address will be updated.

type

String

false

Type of address.

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

Query parameters

No parameters.

Response fields

No response body.

Example request

$ curl 'https://api.middleware.vt.edu/v2/users/20002137/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

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/v2/users/20002137/addresses/home
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of the user.

Query parameters

Parameter

Type

Optional

Description

type

String

false

Type of name.

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

first

String

false

First name.

last

String

false

Last name.

prefix

String

true

Name prefix.

middle

String

true

Middle name.

suffix

String

true

Name suffix.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/20001964/names/preferred
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

type

String

false

Name type to remove.

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

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/20001769
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

type

String

false

Name type to update.

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

Query parameters

No parameters.

Response fields

No response body.

Example request

$ curl 'https://api.middleware.vt.edu/v2/users/20002198/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

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/v2/users/20002198/names/preferred
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

Parameter

Type

Optional

Description

number

Integer

false

Phone number digits.

type

String

false

Phone number type.

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

country

String

true

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

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/48568004174467682/phones/14
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

Remove Phone

DELETE /v2/users/{uid:[0-9]+}/phones/{phoneUid:[0-9]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

phoneUid

Integer

false

Unique identifier of phone number to delete.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/48568002827068691
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/phones/{phoneUid:[0-9]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

phoneUid

Integer

false

Unique identifier of phone number to update.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/48567994923726036/phones/1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

POST /v2/users/{uid:[0-9]+}/{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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

type

String

false

Social identifier type to add.

Must be one of [IMIDS, URIS].

Query parameters

Parameter

Type

Optional

Description

String

false

Key:value ID

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

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://build.api.middleware.vt.edu/v2/users/20002129/uris/awesome:http:%2F%2Fnewgrounds.com
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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: 88

{
  "type" : "AccessDeniedException",
  "code" : 403,
  "message" : "Access is denied"
}

DELETE /v2/users/{uid:[0-9]+}/uris/{id:[0-9]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Integer

false

Id of the social identifier to remove.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/20002209
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

Parameter

Type

Optional

Description

for

String

true

Eligibility item to be checked. If not provided, returns eligibility for all the items in the following list.

Must be one of [HOKIES_SECRET, NETWORK_SECRET, RECOVERY_OPTIONS, TWO_FACTOR, VT_ACCOUNT].

Response fields

No response body.

Example request

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

Example 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: 1; mode=block
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: 25

{
  "TWO_FACTOR" : 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: 1; mode=block
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:[0-9]+}

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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

No parameters.

Response fields

No response body.

Example request

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

Example 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/v2/users/48568003173479921
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

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: 1; mode=block
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:[0-9]+}/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

Parameter

Type

Optional

Description

uid

Integer

false

UID of user.

Query parameters

Parameter

Type

Optional

Description

ssn

String

false

Last four digits of SSN.

Response fields

No response body.

Example request

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

Example response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 20
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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" : 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: 1; mode=block
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

ALUMNI

Name

BANNER

Name

PREFERRED

Person

Virginia Tech

Person

Guest

GUEST

Person

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.