# /status 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). The Access Requests and Grants VCs include the **`credentialStatus`** object with the following fields that provide information on their revocation status:

```json
{
   // ...
   "credentialStatus": {
       "id": "https://vc.<ESS DOMAIN>/status/umZS#801",
       "revocationListCredential": "https://vc.<ESS DOMAIN>/status/umZS",
       "revocationListIndex": "801",
       "type": "RevocationList2020Status"
   },
   // ...
}
```

<table><thead><tr><th width="270.1328125">Field</th><th>Value</th></tr></thead><tbody><tr><td><strong><code>"id"</code></strong></td><td><strong><code>"https://vc.&#x3C;ESS Domain>/status/&#x3C;credential>#&#x3C;idx>"</code></strong><br>The URL of the revocation status for this VC.</td></tr><tr><td><strong><code>"revocationListCredential"</code></strong></td><td><strong><code>"https://vc./status/"</code></strong><br>The URL identifying the VC in the revocation list.</td></tr><tr><td><strong><code>"revocationListIndex"</code></strong></td><td><strong><code>"&#x3C;idx>"</code></strong><br>The bit position (i.e., the index) of the VC’s revocation status.</td></tr><tr><td><strong><code>"type"</code></strong></td><td><strong><code>"RevocationList2020Status"</code></strong></td></tr></tbody></table>

The ESS [Access Grant Service](https://docs.inrupt.com/ess/latest/services/service-access-grant) provides an endpoint where users may revoke an Access Requests/Grants.

For more information, see [RevocationList2020Status](https://w3c-ccg.github.io/vc-status-rl-2020/#revocationlist2020status)

## `/status` Endpoint

The ESS [Access Grant Service](https://docs.inrupt.com/ess/latest/services/service-access-grant) provides the following endpoint for updating the revocation status of issued Access Requests/Grants:

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

Specifically, the endpoint allows for the revocation of the Access Requests/Grants. To revoke an Access Requests/Grants VC, clients can send a **`POST`** request to the endpoint:

{% hint style="warning" %}
**Important**

* Users must be authenticated. The endpoint supports the use of either [Solid-OpenID Connect (OIDC) access token](https://docs.inrupt.com/ess/latest/services/service-oidc) or [UMA token](https://docs.inrupt.com/ess/latest/services/service-uma).
* Only the agent whose WebID matches the Access Request/Grant VC’s **`credentialSubject.id`** can update the status.
* For Access Requests, users must use an application whose Client ID is allowed by the [**`INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSREQUEST`**](https://docs.inrupt.com/ess/latest/services/service-access-grant/..#inrupt_vc_client_id_allow_list_solidaccessrequest) setting.
* For Access Grants, users must use an application whose Client ID is allowed by the [**`INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSGRANT`**](https://docs.inrupt.com/ess/latest/services/service-access-grant/..#inrupt_vc_client_id_allow_list_solidaccessgrant) setting.
  {% endhint %}

<table data-header-hidden><thead><tr><th width="145.15057373046875"></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>/status</code></strong></td></tr><tr><td>Payload</td><td>Status update request object. See <a href="#payload">Payload</a> for details.</td></tr></tbody></table>

Upon successful update, the endpoint returns a status of **`204`** .

{% hint style="info" %}
The **`/status`** endpoint no longer allows the reactivation of revoked Access Requests/Grants. Once revoked, initiate a new Access Request/Grant flow to regain access after revocation.
{% endhint %}

## Payload

The ESS Access Grant service’s **`/status`** endpoint accepts a document of the form:

```json
{
   "credentialId": <VC id>,
   "credentialStatus": [
      { "type": "RevocationList2020Status", "status": 1 }
   ]
}
```

<table><thead><tr><th width="183.87213134765625">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>credentialId</code></strong></td><td>The id value (URL) of the access request/grant VC to update; e.g., a string of the form:<br><strong><code>"https://vc.&#x3C;ESS DOMAIN>/vc/&#x3C;value>"</code></strong></td></tr><tr><td><strong><code>credentialStatus</code></strong></td><td><p>Specify an array of status documents. To revoke ESS-issued Access Requests/Grants, specify a document of the form:<br><strong><code>{ "type": "RevocationList2020Status", "status": 1 }</code></strong><br><br>The status of Access Requests/Grants issued by ESS is indicated through the <a href="https://w3c-ccg.github.io/vc-status-rl-2020/#revocationlist2020status">RevocationList2020Status</a>.<br><br>The <strong><code>status</code></strong> value of <strong><code>1</code></strong> indicates that the Access Request/Grant is to be revoked.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note</strong></p><p>The <strong><code>/status</code></strong> endpoint no longer allows the reactivation of revoked Access Requests/Grants. That is, you can no longer specify <strong><code>"credentialStatus.status": 0</code></strong> in the payload.</p><p>Instead, once an Access Request/Grant is revoked, initiate a new Access Request/Grant flow to regain access.</p></div></td></tr></tbody></table>

## Example

{% hint style="warning" %}
**Important**\
Only the agent whose WebID matches the VC’s **`credentialSubject.id`** can update the status of an Access Request/Grant.
{% endhint %}

For example, assume that **`owliverowner`** has the following access grant as a record of the access granted to **`requestingrabbit`** :

<pre class="language-json"><code class="lang-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"
  ],
<strong>  "id": "https://vc.&#x3C;ESS DOMAIN>/vc/xxxxxx-1234-ffff-5678-abcd99999999",
</strong>  "type": [
    "VerifiableCredential",
    "SolidAccessGrant"
  ],
  "proof": {
    // ... Omitted for brevity
  },
  "credentialStatus": {
    "id": "https://vc.&#x3C;ESS DOMAIN>/status/umZS#801",
    "revocationListCredential": "https://vc.&#x3C;ESS DOMAIN>/status/umZS",
    "revocationListIndex": "801",
<strong>    "type": "RevocationList2020Status"
</strong>  },
  "credentialSubject": {
<strong>    "id": "https://id.&#x3C;ESS DOMAIN>/owliverowner",
</strong>    "providedConsent": {
      "mode": "Read",
      "forPersonalData": "https://storage.&#x3C;ESS DOMAIN>/&#x3C;owliversRootContainer>/getting-started/readingList/myList",
      "hasStatus": "ConsentStatusExplicitlyGiven",
      "isProvidedTo": "https://id.&#x3C;ESS Domain>/requestingrabbit"
    }
  },
  "issuer": "https://vc.&#x3C;ESS DOMAIN>",
  "issuanceDate": "2023-02-10T23:41:39.731Z",
  "expirationDate": "2023-02-10T23:51:43.285Z"
}
</code></pre>

In the example Access Grant,

* **`id`** is **`"https://vc.<ESS DOMAIN>/vc/xxxxxx-1234-ffff-5678-abcd99999999"`** . When changing the revocation status of this Access Grant, use this value in the **`credentialId`** .
* **`credentialStatus.type`** is **`"RevocationList2020Status"`** . When revoking this Access Grant, use this value in the **`credentialStatus.type`** field.
* **`crendentialSubject.id`** is **`"https://id.<ESS DOMAIN>/owliverowner"`** . This indicates that **`"https://id.<ESS DOMAIN>/owliverowner"`** can modify the revocation status of this Access Grant.

Then to revoke this Access Grant, the **`owliverowner`** can post the following payload to **`/status`** endpoint:

```json
{
   "credentialId": "https://vc.<ESS DOMAIN>/vc/xxxxxx-1234-ffff-5678-abcd99999999",
   "credentialStatus": [
      { "type": "RevocationList2020Status", "status": "1" }
   ]
}
```

Upon successful update, the endpoint returns a status of **`204`** .

After the Access Grant has been revoked, if you [verify the revoked access grant](https://docs.inrupt.com/ess/latest/services/service-access-grant/service-access-grant-verifier), you get the following result:

<pre class="language-json"><code class="lang-json">{
  "checks": [
    "issuanceDate",
    "proof",
    "expirationDate",
    "credentialStatus"
  ],
  "errors": [
<strong>    "credentialStatus validation has failed: credential has been revoked"
</strong>  ],
  "warnings": []
}
</code></pre>

If **`requestingrabbit`** needs to access the resource, **`requestingrabbit`** must create a new request access to **`owliverowner`** .