/status Endpoint

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

ESS serializes the Access Requests and Grants as Verifiable Credentials (VCs). The Access Requests and Grants VCs include the credentialStatus object with the following fields that provide information on their revocation status:

{
   // ...
   "credentialStatus": {
       "id": "https://vc.<ESS DOMAIN>/status/umZS#801",
       "revocationListCredential": "https://vc.<ESS DOMAIN>/status/umZS",
       "revocationListIndex": "801",
       "type": "RevocationList2020Status"
   },
   // ...
}

Field	Value
"id"	"https://vc.<ESS Domain>/status/<credential>#<idx>" The URL of the revocation status for this VC.
"revocationListCredential"	"https://vc./status/" The URL identifying the VC in the revocation list.
"revocationListIndex"	"<idx>" The bit position (i.e., the index) of the VC’s revocation status.
"type"	"RevocationList2020Status"

The ESS Access Grant Service provides an endpoint where users may revoke an Access Requests/Grants.

For more information, see RevocationList2020Status

/status Endpoint

The ESS Access Grant Service provides the following endpoint for updating the revocation status of issued Access Requests/Grants:

https://vc.<ESS Domain>/status

Specifically, the endpoint allows for the revocation of the Access Requests/Grants. To revoke an Access Requests/Grants VC, clients can send a POST request to the endpoint:

Important

• Users must be authenticated. The endpoint supports the use of either Solid-OpenID Connect (OIDC) access token or UMA token.

• Only the agent whose WebID matches the Access Request/Grant VC’s credentialSubject.id can update the status.

• For Access Requests, users must use an application whose Client ID is allowed by the INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSREQUEST setting.

• For Access Grants, users must use an application whose Client ID is allowed by the INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSGRANT setting.

Method	POST
Content-Type	application/json
Endpoint	https://vc.<ESS Domain>/status
Payload	Status update request object. See Payload for details.

Upon successful update, the endpoint returns a status of 204 .

The /status endpoint no longer allows the reactivation of revoked Access Requests/Grants. Once revoked, initiate a new Access Request/Grant flow to regain access after revocation.

Payload

The ESS Access Grant service’s /status endpoint accepts a document of the form:

{
   "credentialId": <VC id>,
   "credentialStatus": [
      { "type": "RevocationList2020Status", "status": 1 }
   ]
}

Field	Description
credentialId	The id value (URL) of the access request/grant VC to update; e.g., a string of the form: "https://vc.<ESS DOMAIN>/vc/<value>"
credentialStatus	Specify an array of status documents. To revoke ESS-issued Access Requests/Grants, specify a document of the form: { "type": "RevocationList2020Status", "status": 1 } The status of Access Requests/Grants issued by ESS is indicated through the RevocationList2020Status. The status value of 1 indicates that the Access Request/Grant is to be revoked. Note The /status endpoint no longer allows the reactivation of revoked Access Requests/Grants. That is, you can no longer specify "credentialStatus.status": 0 in the payload. Instead, once an Access Request/Grant is revoked, initiate a new Access Request/Grant flow to regain access.

Example

Important Only the agent whose WebID matches the VC’s credentialSubject.id can update the status of an Access Request/Grant.

For example, assume that owliverowner has the following access grant as a record of the access granted to requestingrabbit :

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://schema.inrupt.com/credentials/v2.jsonld",
    "https://w3id.org/security/data-integrity/v1",
    "https://w3id.org/vc-revocation-list-2020/v1",
    "https://w3id.org/vc/status-list/2021/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "https://vc.<ESS DOMAIN>/vc/xxxxxx-1234-ffff-5678-abcd99999999",
  "type": [
    "VerifiableCredential",
    "SolidAccessGrant"
  ],
  "proof": {
    // ... Omitted for brevity
  },
  "credentialStatus": {
    "id": "https://vc.<ESS DOMAIN>/status/umZS#801",
    "revocationListCredential": "https://vc.<ESS DOMAIN>/status/umZS",
    "revocationListIndex": "801",
    "type": "RevocationList2020Status"
  },
  "credentialSubject": {
    "id": "https://id.<ESS DOMAIN>/owliverowner",
    "providedConsent": {
      "mode": "Read",
      "forPersonalData": "https://storage.<ESS DOMAIN>/<owliversRootContainer>/getting-started/readingList/myList",
      "hasStatus": "ConsentStatusExplicitlyGiven",
      "isProvidedTo": "https://id.<ESS Domain>/requestingrabbit"
    }
  },
  "issuer": "https://vc.<ESS DOMAIN>",
  "issuanceDate": "2023-02-10T23:41:39.731Z",
  "expirationDate": "2023-02-10T23:51:43.285Z"
}

In the example Access Grant,

• id is "https://vc.<ESS DOMAIN>/vc/xxxxxx-1234-ffff-5678-abcd99999999" . When changing the revocation status of this Access Grant, use this value in the credentialId .

• credentialStatus.type is "RevocationList2020Status" . When revoking this Access Grant, use this value in the credentialStatus.type field.

• crendentialSubject.id is "https://id.<ESS DOMAIN>/owliverowner" . This indicates that "https://id.<ESS DOMAIN>/owliverowner" can modify the revocation status of this Access Grant.

Then to revoke this Access Grant, the owliverowner can post the following payload to /status endpoint:

{
   "credentialId": "https://vc.<ESS DOMAIN>/vc/xxxxxx-1234-ffff-5678-abcd99999999",
   "credentialStatus": [
      { "type": "RevocationList2020Status", "status": "1" }
   ]
}

Upon successful update, the endpoint returns a status of 204 .

After the Access Grant has been revoked, if you verify the revoked access grant, you get the following result:

{
  "checks": [
    "issuanceDate",
    "proof",
    "expirationDate",
    "credentialStatus"
  ],
  "errors": [
    "credentialStatus validation has failed: credential has been revoked"
  ],
  "warnings": []
}

If requestingrabbit needs to access the resource, requestingrabbit must create a new request access to owliverowner .