# /verify Endpoint

ESS supports an [authorization mechanism based on Access Requests and Grants](https://docs.inrupt.com/security/authorization/access-requests-grants).

ESS serializes the Access Requests and Grants as [Verifiable Credentials (VCs)](https://docs.inrupt.com/reference/glossary#verifiable-credential) and provides a verification endpoint for these VCs.

## `/verify` Endpoint

The ESS [Access Grant Service](https://docs.inrupt.com/ess/latest/services/service-access-grant) provides the following endpoint for Access Request/Grant VC verification:

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

To verify an Access Request/Grant, clients can send the verification request to the endpoint:

<table data-header-hidden><thead><tr><th width="144.944580078125"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><strong><code>POST</code></strong></td></tr><tr><td>Content-Type</td><td><strong><code>application/json</code></strong></td></tr><tr><td>Endpoint</td><td><strong><code>https://vc.&#x3C;ESS Domain>/verify</code></strong></td></tr><tr><td>Payload</td><td>Verification request object. See <a href="#input-access-request-grant-vc">Input: Access Request/Grant VC</a> for details.</td></tr></tbody></table>

The **`/verify`** endpoint (also referred to as the Verifier on this page) implements the verify portion of the [VC API specification](https://w3c-ccg.github.io/vc-api/#verifying).

{% hint style="info" %}
The [VC API specification](https://w3c-ccg.github.io/vc-api/#issue-credential) is in Draft status. Features based on draft specifications are subject to change.
{% endhint %}

## 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](https://w3c-ccg.github.io/lds-ed25519-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 :

<table><thead><tr><th width="216.42181396484375">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>type</code></strong></td><td>When validating a Solid access request, the VC’s <strong><code>type</code></strong> field must include <strong><code>"SolidAccessRequest"</code></strong>.<br>When validating a Solid access grant, the VC’s <strong><code>type</code></strong> field must include <strong><code>"SolidAccessGrant"</code></strong>.</td></tr><tr><td><strong><code>credentialSubject.id</code></strong></td><td>The VC’s <strong><code>credentialSubject.id</code></strong> field must be a WebID.</td></tr><tr><td><strong><code>proof.domain</code></strong></td><td>The VC’s <strong><code>proof.domain</code></strong> field must be set to solid.</td></tr></tbody></table>

## Input: Access Request/Grant VC

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

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

* **`verifiableCredential`** accepts a VC JSON-LD document.

For details, see: [VC Verifier API (OpenAPI specification)](https://w3c-ccg.github.io/vc-api/verifier.html#operation/verifyCredential)

## Output: Verification Results

The Verifier returns a JSON object:

```json
{
  "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:

```json
{
  "@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`** ):

```json
{
   "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:

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

{% hint style="info" %}
**Note**\
Since the **`expirationDate`** is not present in the input VC, the **`expirationDate`** check did not occur, and thus is omitted from the output.
{% endhint %}