/query Endpoint#

Added in version 2.3.

Starting in version 2.0, ESS supports an authorization mechanism based on access requests and grants.

ESS serializes the access requests and grants as Verifiable Credentials (VCs). As of version 2.3, 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 tokens or UMA tokens.

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 Verifiable Credentials (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
On this page