/status Endpoint#

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). 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.<ESS Domain>/status/<credential>"

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" [1]

ESS Access Grant service provides an endpoint where users may revoke an access request/grant.

/status Endpoint#

The ESS Access Grant service provides the following endpoint for updating the revocation status of issued access requests/grants: [2]

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

Specifically, the endpoint allows for the revocation of the access requests/grants. To revoke an access request/grant VC, clients can send a POST request to the endpoint:

Important

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.

Payload#

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

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

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 document(s). 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

Starting in 2.2, 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/v1.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.

On this page