# /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/2.3/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/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`** ):

```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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inrupt.com/ess/2.3/services/service-access-grant/service-access-grant-verifier.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.