/verify 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 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 [1].

Verification Checks#

The Verifier performs the following verification checks on the access request/grant 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 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:

Output: Verification Results#

The Verifier returns a JSON object:

{
  "checks": [
    "issuanceDate",
    "proof",
    "expirationDate",
    "credentialStatus"
  ],
  "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://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/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.

On this page