/query Endpoint

ESS supports an authorization mechanism based on Access Requests and Grants.

ESS serializes the Access Requests and Grants as Verifiable Credentials (VCs) The query endpoint provides an optimized mechanism to search and filter these VCs.

/query Endpoint

The ESS Access Grant Service provides an endpoint with the following URL:

https://vc.<ESS DOMAIN>/query

Note Access to the /query endpoint requires users to be authenticated. The endpoint supports the use of either Solid-OpenID Connect (OIDC) access token or UMA token.

To query for Access Requests or Grants, clients can send a request to the endpoint:

Method	GET
Endpoint	https://vc.<ESS DOMAIN>/query
Query Parameters	Parameters that control which results are returned. See Input: Query Parameters for details.

Behavior

The ESS /query endpoint adds support for retrieving access credentials based on a defined set of filters. Please see Input: Query Parameters for details.

The results are be available via a pageable interface. Clients can use Link headers in the response to navigate through the result pages. The query result body consists of a JSON object that lists access credentials formatted as VCs . Please see Output: Query Response for details.

Input: Query Parameters

type	One of SolidAccessRequest, SolidAccessGrant, SolidAccessDenial
status	One of Pending, Denied, Granted, Canceled, Expired, Active, Revoked. Please see Status values for details.
fromAgent	The WebID of the creator of the access credential.
toAgent	The WebID of the recipient of the access credential.
resource	The URL of a storage location specified in the access credential.
purpose	The URL of a purpose identifier specified in the access credential.
issuedWithin	One of P1D (one day), P7D (one week) P1M (one month) or P3M (three months). This parameter will limit the results to those that were issued within the specified time period.
revokedWithin	One of P1D (one day), P7D (one week) P1M (one month) or P3M (three months). This parameter is only relevant when status is Revoked or Canceled. This will limit the results to those that were revoked within the specified time period.
pageSize	This controls the maximum number of results in a page of results. By default, this value is 20. It may not exceed 100.
page	This value is an opaque cursor used to navigate through result pages. A client should make use of this value when consuming Link headers in a response but should not need to set this value independently.

Status values

Active

This status value will list Access Grants that have not expired and have not been revoked. This value is only relevant when type is SolidAccessGrant .

Expired

This status value will list Access Grants that have expired. This value is only relevant when type is SolidAccessGrant .

Revoked

This status value will list Access Grants that have been revoked. This value is only relevant when type is SolidAccessGrant .

Pending

This status value will list Access Requests that do not have a corresponding Access Grant or Access Denial. This value is only relevant when type is SolidAccessRequest .

Granted

This status value will list Access Requests that have a corresponding Access Grant. This value is only relevant when type is SolidAccessRequest .

Denied

This status value will list Access Requests that have a corresponding Access Denial. This also can be used with Access Denial types. This value is relevant when the type is either SolidAccessRequest or SolidAccessDenial .

Canceled

This status value will list Access Requests that have been revoked (i.e. canceled). This value is only relevant when type is SolidAccessRequest .

Output: Query Response

The /query endpoint returns a JSON object containing an individual page of results as part of a pageable interface. By default, each page of results will contain up to 20 items.

{
  "items": [
    { // Matching access credential VC },
    { // Matching access credential VC },
    ...
  ]
}

When there are multiple pages of results, Link headers will point to the first , last , prev and next page, as appropriate. The first page, for example, will not include a prev link.

Example Link headers are included below:

Link: </query?type=SolidAccessGrant&status=Active&page=323904ad>; rel="first"
Link: </query?type=SolidAccessGrant&status=Active&page=3d224607>; rel="prev"
Link: </query?type=SolidAccessGrant&status=Active&page=6af7d740>; rel="next"
Link: </query?type=SolidAccessGrant&status=Active&page=35faea55>; rel="last"

The page parameter is used to navigate through an ordered list of pages. Client applications should treat this value as opaque.

Examples

These examples describe some common queries that application developers may use. In each example, the URL is formatted across multiple lines to improve readability. Please note that all URI parameters are URL-encoded; this is especially important for URIs that contain hash fragments, i.e. sections beginning with the character # .

Example 1

The following query searches for all pending Access Requests from the last week, targeting a particular user, such as the current user of an application. The results of this query may represent the list of outstanding requests that a user should either approve or reject.

/query?type=SolidAccessRequest
    &status=Pending
    &issuedWithin=P7D
    &toAgent=https%3A%2F%2Fid.example%2Fusername

Example 2

The following query searches for all Access Grants that a particular user has issued in the last month. This might allow a user to understand who has been granted access to their Storage to decide if access needs to be changed for anyone.

/query?type=SolidAccessGrant
    &status=Active
    &issuedWithin=P1M
    &fromAgent=https%3A%2F%2Fid.example%2Fusername

Example 3

The following query searches for all Access Requests made by a particular user in the last three months that have been denied.

/query?type=SolidAccessRequest
    &status=Denied
    &issuedWithin=P3M
    &fromAgent=https%3A%2F%2Fid.example%2Fusername

Example 4

The following query searches for all Access Grants that a user has received from others.

/query?type=SolidAccessGrant
    &status=Active
    &toAgent=https%3A%2F%2Fid.example%2Fusername