/status Endpoint#

New in version 2.0.

Starting in version 2.0, ESS supports an authorization mechanism based on access requests and grants. In 2.0, the access requests and grants are serialized as a Verifiable Credentials (VCs).

As part of supporting access requests and grants, ESS provides a service where users may revoke an existing Verifiable Credential (or reactivate a revoked VC).

/status Endpoint#

The ESS VC service provides the following endpoint for managing the revocation status of issued VCs:

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

To update the status of a VC, clients can send the status update request to the endpoint:

Important

Only the agent whose WebID matches the VC’s credentialSubject.id can update the VC status.

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 1.

Payload#

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

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

credentialId

The id value of the 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 VCs issued by ESS VC service, specify a document of the form:

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

The status of VCs issued by ESS is indicated through the RevocationList2020Status. Specify a status value of:

  • 1 to revoke a VC.

  • 0 to reactivate a VC.

See also:

Example#

Important

Only the agent whose WebID matches the VC’s credentialSubject.id can update the status of a VC.

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

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1",
    "https://w3id.org/vc-revocation-list-2020/v1",
    "https://vc.<ESS Domain>/credentials/v1"
  ],
  "credentialStatus": {
    "id": "https://vc.<ESS Domain>/status/aZZZ#801",
    "revocationListCredential": "https://vc.<ESS Domain>/status/aZZZ",
    "revocationListIndex": "801",
    "type": "RevocationList2020Status"
  },
  "credentialSubject": {
    "providedConsent": {
      "mode": "http://www.w3.org/ns/auth/acl#Read",
      "hasStatus": "https://w3id.org/GConsent#ConsentStatusExplicitlyGiven",
      "isProvidedToPerson": "https://id.<ESS Domain>/requestingrabbit",
      "forPersonalData": [
        "https://storage.<ESS DOMAIN>/<owliversPodIdentifier>/getting-started/readingList/myList"
      ]
    },
    "id": "https://id.<ESS DOMAIN>/owliverowner"
  },
  "id": "https://vc.<ESS DOMAIN>/vc/9876abcd-1234-ffff-5678-abcd99999999",
  "issuanceDate": "2021-10-26T23:43:12.422Z",
  "issuer": "https://vc.<ESS DOMAIN>",
  "proof": {
    // ... Omitted for brevity
  },
  "type": [
    "VerifiableCredential",
    "SolidAccessGrant"
  ]
}

In the example VC,

  • credentialStatus.type is "RevocationList2020Status". When revoking this VC, 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 VC.

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

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

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

After the VC has been revoked, a verification request yields the following result:

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

The VC API specification is in Draft status. Features based on draft specifications are subject to change.