Ctrl+K
Archived docs. ESS 2.0 has reached end of life.

/status Endpoint#

New 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).

/status Endpoint#

The ESS Access Grant service provides the following endpoint for managing 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

  • Only the agent whose WebID matches the access request/grant VC’s credentialSubject.id can update the status.

  • If INRUPT_VC_CLIENT_ID_ALLOW_LIST is set, users must use an application whose Client ID is in the list.

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 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 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://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 access grant,

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

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

Then to revoke this access grant, 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 access grant has been revoked, a verification request yields the following result:

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