# /status Endpoint

ESS supports an [authorization mechanism based on Access Requests and Grants](https://github.com/inrupt/docs-gitbook/blob/main/ess/security/authorization/access-requests-grants/README.md).

ESS serializes the Access Requests and Grants as [Verifiable Credentials (VCs)](/reference/glossary.md#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](/ess/2.6/services/service-access-grant.md) 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](/ess/2.6/services/service-access-grant.md) 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](/ess/2.6/services/service-oidc.md) or [UMA token](/ess/2.6/services/service-uma.md).
* 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`**](/ess/2.6/services/service-access-grant.md#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`**](/ess/2.6/services/service-access-grant.md#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](/ess/2.6/services/service-access-grant/service-access-grant-verifier.md), 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`** .


---

# 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.6/services/service-access-grant/service-access-grant-status.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.