/verify Endpoint

ESS supports an authorization mechanism based on Access Requests and Grants.

ESS serializes the Access Requests and Grants as Verifiable Credentials (VCs) and provides a verification endpoint for these VCs.

/verify Endpoint

The ESS Access Grant Service provides the following endpoint for Access Request/Grant VC verification:

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

To verify an Access Request/Grant, 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: Access Request/Grant VC for details.

The /verify endpoint (also referred to as the Verifier on this page) implements the verify portion of the VC API specification.

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

Verification Checks

The Verifier performs the following verification checks on the Access Request/Grant 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 is active; specifically:

  • Checks that the VCs effective period has started (i.e., has a future issuance date).

  • Checks that the VCs have not expired (i.e., has a past expiration date).

In addition, the Verifier performs the following Solid checks on the Access Request/Grant 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: Access Request/Grant VC

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

{
   "verifiableCredential": <Access Request/Grant VC to verify>,
   "options": <options>
}

• verifiableCredential accepts a VC JSON-LD document.

For details, see: VC Verifier API (OpenAPI specification)

Output: Verification Results

The Verifier returns a JSON object:

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

• checks lists the checks performed during verification.

  {% hint style="info" %} Note The expirationDate check only occurs if an expiration date is present in the VC. {% endhint %}

• 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://schema.inrupt.com/credentials/v2.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/bee01024-9cf8-4e4a-b70a-03242a980cce",
  "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>/<owliversRootContainer>/getting-started/readingList/myList"
      ]
    },
    "id": "https://id.<ESS DOMAIN>/requestingrabbit",
  },
  "id": "https://vc.<ESS DOMAIN>/vc/xxxxxx...",
  "issuanceDate": "2021-10-25T03:21:58.512Z",
  "expirationDate": "2023-05-08T04:36:25.609Z",
  "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>/<owliversRootContainer>/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": [
    "issuanceDate",
    "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.