> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grail.oro.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Revoke API Key

> Permanently revokes an API key. Revocation is immediate and irreversible.

## Overview

Revokes an API key so that no further requests can authenticate with it. Revocation is permanent and takes effect immediately — the next request using the revoked key returns `401 unauthorized`.

<Warning>
  Revocation is irreversible. To restore access, mint a new key via the [challenge-response flow](/api-reference/authentication/request-challenge).
</Warning>

## Headers

<ParamField header="x-api-key" type="string" required>
  A valid `PARTNER` scope key for the partner that owns the key being revoked.
</ParamField>

## Path Parameters

<ParamField path="key_id" type="string" required>
  UUID of the key to revoke. Available from [List API Keys](/api-reference/partner/list-api-keys).
</ParamField>

## Response

<ResponseField name="key_id" type="string">
  UUID of the revoked key.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"revoked"` on success.
</ResponseField>

<ResponseField name="revoked_at" type="string">
  ISO-8601 timestamp of the revocation.
</ResponseField>

## Errors

| HTTP | `error`           | When                                                       |
| ---- | ----------------- | ---------------------------------------------------------- |
| 400  | `already_revoked` | The key is already in `revoked` status                     |
| 401  | `unauthorized`    | Missing or invalid `x-api-key`                             |
| 404  | `key_not_found`   | `key_id` does not exist, or belongs to a different partner |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    https://grail-stack-dev.onrender.com/v1/partner/api-keys/0c9bd7e4-6b2e-4f3a-a9a7-1f6e5d4c3b2a/revoke \
    -H "x-api-key: grail_partner_<hex>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "key_id": "0c9bd7e4-6b2e-4f3a-a9a7-1f6e5d4c3b2a",
    "status": "revoked",
    "revoked_at": "2026-04-19T13:00:00.000Z"
  }
  ```
</ResponseExample>