# 更新 ／ 停用 ／ 啟用 API Key

此 API 用於更新指定 API Key 的 metadata 或到期時間，僅 **Master Key** 可呼叫此 API。  
此 API 同時支援以下操作：

- 更新 metadata

- 延長或縮短有效期限

- 停用 API Key：將 `expires_at` 設為目前時間或過去的時間

- 重新啟用 API Key：將 `expires_at` 設為未來的時間，或設為 `null`

- 移除到期限制：將 `expires_at` 設為 `null`

系統不會再次回傳 API Key 明文。

:::warning[⚠️]

**省略** `expires_at` **會重設到期時間。** 只要 Request Body 沒有帶 `expires_at` 欄位（例如只想更新 metadata），系統會將到期時間重設為「本次請求時間起 90 天」，**不會保留原本的到期設定**。若只想更新 metadata 而不變動到期時間，請在 Request Body 中明確帶上原本的 `expires_at` 值（原本不過期者請帶 `null`）。

:::

**Method：** `PATCH`（建議一律使用）  
**Path：** `/v1/api-keys/{id}`  
**備註：** `PUT /v1/api-keys/{id}` 仍可運作，但已標記為 deprecated，僅供舊版相容，請改用 `PATCH`。

```bash
curl -X 'PATCH' \
  'http://127.0.0.1:8000/v1/api-keys/3f90f7e3-7ec5-4c68-8bd1-38f54e90d390' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <master-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "customer_name": "ACME Corp",
      "contact": "alice@example.com",
      "purpose": "UAT extended"
    },
    "expires_at": "2026-12-16T00:00:00Z"
  }'
```

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | PATCH |
| accept | application/json |
| Authorization | `Bearer <master-key>` |
| Content-Type | application/json |

#### Path Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| id | string | uuid，要更新的 API Key id | true |

#### Request Payload

以下範例會立即停用 API Key（將到期時間設為過去的時間），並清空 metadata：

```json
{
  "metadata": null,
  "expires_at": "2026-07-20T00:00:00Z"
}
```

**Field Explanation**

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| metadata | object \| null | 更新 metadata。帶入物件時會**整個取代**原本的 metadata（不是合併）；為 null 時清空為 `{}`；省略時維持不變 | false |
| expires_at | string \| null | 更新到期時間；可指定 ISO8601 timestamp 或 null。**省略時會重設為請求時間起 90 天** | false |

**補充說明：**

- `metadata` = object：以新的物件取代原本的 metadata。

- `metadata` = `null`：移除 metadata，回到空物件 `{}`。

- `metadata` 省略：metadata 維持不變。

- `expires_at` = 目前時間或過去的 ISO8601 timestamp（例如 `"2026-07-20T00:00:00Z"`）：立即失效，視同停用。

- `expires_at` = 未來的 ISO8601 timestamp（例如 `"2026-12-16T00:00:00Z"`）：指定新的到期時間；對已停用的 Key 而言即為重新啟用。

- `expires_at` = `null`：移除到期限制（不會過期）；對已停用的 Key 而言即為重新啟用。

- `expires_at` 省略：到期時間重設為本次請求時間起 90 天，**不會保留原本的到期設定**。

- 建議 `expires_at` 一律帶上時區（例如 `Z` 或 `+08:00`）。

- API Key 過期（含停用）後，使用該 Key 呼叫 API 會回傳 `AUTH_003`。

#### Response Body

回傳更新後的 API Key 物件（欄位說明請參考 [取得所有 API Key 列表](https://privstation-docs.apmic.ai/latest/privai-400/取得所有-api-key-列表.md) 中的「API Key 物件」一節）。

```json
{
  "id": "3f90f7e3-7ec5-4c68-8bd1-38f54e90d390",
  "object": "api_key",
  "redacted_value": "sk-xxxx...abcd",
  "metadata": {},
  "created_at": "2026-06-16T00:00:00Z",
  "expires_at": "2026-07-20T00:00:00Z"
}
```

**Field Explanation**

| Field | Detail |
| --- | --- |
| id | API Key 的唯一鍵，UUID |
| object | 物件類型，固定為 `api_key` |
| redacted_value | 遮罩後的 API Key |
| metadata | API Key 的描述資訊 |
| created_at | API Key 建立時間 |
| expires_at | API Key 到期時間；null 代表不會過期 |

#### 常見錯誤

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| AUTH_001 | 401 | 缺少 `Authorization` header |
| AUTH_002 | 403 | `Authorization` 帶入的不是 Master Key（包含使用租戶 Key 呼叫） |
| API_KEY_001 | 404 | 指定的 API Key id 不存在 |

`id` 不是合法的 UUID、或 `expires_at` 格式錯誤時，會回傳 HTTP 422。錯誤格式請參考 [例外狀況處理](https://privstation-docs.apmic.ai/latest/privai-400/例外狀況處理.md)。
