/verify 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).

To support access requests and grants, ESS provides a verification service for these VCs.

/verify Endpoint#

The ESS VC service provides the following endpoint for VC verification:

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

To verify a VC, clients can send the verification request to the endpoint:

Method:

POST

Content-Type

application/json

Endpoint:

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

Payload:

Verification request object. See Input: Verifiable Credential for details.

The ESS VC service’s /verify endpoint (also referred to as the Verifier on this page) implements the verify portion of the VC API specification [1].

Verification Checks#

The Verifier performs the following verification checks on Verifiable Credentials (VCs):

  • Checks the authenticity of the VCs. Specifically, the Verifier performs Ed25519 signature suite 2020 verifications.

  • Checks that the VCs have not been revoked.

  • Checks that the VCs have not expired.

In addition, the Verifier performs the following Solid checks on the VCs:

Field

Description

type
When validating a Solid access request, the VC’s type field must include "SolidAccessRequest".
When validating a Solid access grant, the VC’s type field must include "SolidAccessGrant".

credentialSubject.id

The VC’s credentialSubject.id field must be a WebID.

proof.domain

The VC’s proof.domain field must be set to solid.

Input: Verifiable Credential#

The Verifier endpoint (/verify) accepts a document of the form:

{
   "verifiableCredential": <Verifiable Credential to verify>,
   "options": <options>
}

  • verifiableCredential accepts a VC JSON-LD document.

For details, see:

Output: Verification Results#

The Verifier returns a JSON object:

{
  "checks": [
    "proof",
    "credentialStatus",
    "expirationDate"
  ],
  "errors": [],
  "warnings": []
}

  • checks lists the checks performed during verification.

    Note

    The expirationDate check only occurs if an expiration date is present in the VC.

  • errors lists any errors that occurred during verification.

  • warnings lists any warnings that occurred during verification.

Example#

The following is a sample access request VC:

{
  "@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/SkbE#0",
    "revocationListCredential": "https://vc.<ESS DOMAIN>/status/SkbE",
    "revocationListIndex": "0",
    "type": "RevocationList2020Status"
  },
  "credentialSubject": {
    "hasConsent": {
      "mode": [
        "http://www.w3.org/ns/auth/acl#Read"
      ],
      "hasStatus": "https://w3id.org/GConsent#ConsentStatusRequested",
      "isConsentForDataSubject": "https://id.<ESS DOMAIN>/owliverowner",
      "forPersonalData": [
        "https://storage.<ESS DOMAIN>/<owliversPodIdentifier>/getting-started/readingList/myList"
      ]
    },
    "id": "https://id.<ESS DOMAIN>/requestingrabbit",
  },
  "id": "https://vc.<ESS DOMAIN>/vc/xxxxxx...",
  "issuanceDate": "2021-10-25T03:21:58.512Z",
  "issuer": "https://vc.<ESS DOMAIN>",
  "proof": {
    "created": "2021-10-25T03:21:58.708Z",
    "domain": "solid",
    "proofPurpose": "assertionMethod",
    "proofValue": "xxxxxx........",
    "type": "Ed25519Signature2020",
    "verificationMethod": "https://vc.<ESS DOMAIN>/key/xxxxx...."
  },
  "type": [
    "VerifiableCredential",
    "SolidAccessRequest"
  ]
}

To verify the VC, post the following payload, where the "verifiableCredential" field is set to the VC to be verified, to the Verifier endpoint (/verify):

{
   "verifiableCredential": {
     "@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/SkbE#0",
       "revocationListCredential": "https://vc.<ESS DOMAIN>/status/SkbE",
       "revocationListIndex": "0",
       "type": "RevocationList2020Status"
     },
     "credentialSubject": {
       "hasConsent": {
         "mode": [
           "http://www.w3.org/ns/auth/acl#Read"
         ],
         "hasStatus": "https://w3id.org/GConsent#ConsentStatusRequested",
         "isConsentForDataSubject": "https://id.<ESS DOMAIN>/owliverowner",
         "forPersonalData": [
           "https://storage.<ESS DOMAIN>/<owliversPodIdentifier>/getting-started/readingList/myList"
         ]
       },
       "id": "https://id.<ESS DOMAIN>/requestingrabbit",
     },
     "id": "https://vc.<ESS DOMAIN>/vc/xxxxxx...",
     "issuanceDate": "2021-10-25T03:21:58.512Z",
     "issuer": "https://vc.<ESS DOMAIN>",
     "proof": {
       "created": "2021-10-25T03:21:58.708Z",
       "domain": "solid",
       "proofPurpose": "assertionMethod",
       "proofValue": "xxxxxx........",
       "type": "Ed25519Signature2020",
       "verificationMethod": "https://vc.<ESS DOMAIN>/key/xxxxx...."
     },
     "type": [
       "VerifiableCredential",
       "SolidAccessRequest"
     ]
   }
}

Upon successful verification, the endpoint returns the following:

{
  "checks": [
    "proof",
    "credentialStatus"
  ],
  "errors": [],
  "warnings": []
}

Note

Since the expirationDate is not present in the input VC, the expirationDate check did not occur, and thus is omitted from the output.