/status Endpoint#

Added in version 2.0.

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) and provides an endpoint where users may revoke an existing access request/grant (or reactivate a revoked access request/grant). The access requests and grants VCs include the credentialStatus [1] 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"

/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

To update the status of 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.

The /status endpoint implements the update status portion of the VC API specification [2].

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": <"0"|"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). For access requests/grants issued by ESS Access Grant service, specify a document of the form:

{ "type": "RevocationList2020Status", "status": <0|1> }

The status of access requests/grants issued by ESS is indicated through the RevocationList2020Status. Specify a status value of:

  • 1 to revoke.

  • 0 to reactivate.

See also:

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": []
}
On this page