# Revoke API Key

- **Method:** `DELETE`
- **Path:** `/api/v1/api-keys/{key_id}`
- **Operation ID:** `revoke_api_key`
- **Tags:** identity

Revoke one of this tenant's keys. The row stays and `revoked_at` is set; the key stops at the gate.

Never deleted, because `runs.created_by` points at it: a revoked key that vanished would leave every
run it started attributed to nothing. An id belonging to another tenant is the same 404 an id nobody
ever minted gets, so this route cannot be used to learn which key ids are real.

## Effective servers

- `https://api.saram.sh`

  Saram

## Authentication

- **HTTPBearer**: HTTP bearer

  a Saram API key (`sk_saram_<env>_...`) or a person's AuthKit access token, as `Authorization: Bearer <credential>`. Both are told apart by shape and produce the same principal.

## Path parameters

- **`key_id` (required)**: `string`

## Responses

### 200 Successful Response

**Content type:** `application/json`

schema: `ApiKeySummary`, no additional properties

One of this tenant's machine keys, as the list and the revocation answer it. The secret is not here.

- **`created_at` (required)**: `string`, format: `date-time`
- **`created_by` (required)**: `string`

  usr\_... for a person who minted it from the dashboard, operator for the CLI.
- **`id` (required)**: `string`
- **`name` (required)**: `string`
- **`scopes` (required)**: `array of string`
- **`expires_at`**: `string | null`, format: `date-time`
- **`last_used_at`**: `string | null`, format: `date-time`

  When this key last got through the gate, to a few minutes: it answers whether anything is still using the key before you revoke it, which does not need the last second.
- **`revoked_at`**: `string | null`, format: `date-time`

  Set on the record DELETE answers with. The row stays; the key stops working.

**Example:**

```json
{
  "id": "",
  "name": "",
  "scopes": [
    ""
  ],
  "created_by": "",
  "created_at": "",
  "last_used_at": "",
  "expires_at": "",
  "revoked_at": ""
}
```

### 403 this credential may not mint keys: an API key without the keys:admin scope, or a person whose role in this tenant is not owner or admin

### 404 no key of this tenant's has that id - deliberately the same answer whether the id belongs to nobody or to another tenant, so that a 404 cannot be used to enumerate key ids

### 422 Validation Error

**Content type:** `application/json`

schema: `HTTPValidationError`

- **`detail`**: `array`

  **Items:**

  schema: `ValidationError`
  - **`loc` (required)**: `array of (string | integer)`
  - **`msg` (required)**: `string`
  - **`type` (required)**: `string`
  - **`ctx`**: `object`
  - **`input`**: `any`

**Example:**

```json
{
  "detail": [
    {
      "loc": [
        ""
      ],
      "msg": "",
      "type": "",
      "input": null,
      "ctx": {}
    }
  ]
}
```

## Schemas

- `ApiKeySummary` — shown above.
- `HTTPValidationError` — shown above.
- `ValidationError` — shown above.