# 更新 / 停用 / 啟用 API Key

此 API 用於更新指定 API Key 的 metadata 或到期時間，僅 **Master Key** 可呼叫此 API。

此 API 同時支援以下操作：

- 更新 metadata

- 延長或縮短有效期限

- 停用 API Key：將 expires_at 設為目前時間

- 重新啟用 API Key：將 expires_at 設定為未來時間

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

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

```javascript
curl -X 'PUT' \
  '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-06-16T00:00:00Z"
  }'
```

#### Request Headers

| **Key** | **Value** |
| --- | --- |
| Request Method | PUT |
| accept | application/json |
| Authorization | Bearer &lt;master-key> |
| Content-Type | application/json |

#### Query Parameters

| **Field** | **Type** | **Note** | **Required** |
| --- | --- | --- | --- |
| id | string | uuid | true |

#### Request Payload

```javascript
{
  "metadata": null,
  "expires_at": "now"
}
```

**Field Explanation**

| **Field** | **Type** | **Note** | **Required** |
| --- | --- | --- | --- |
| metadata | object | null | 更新 metadata；若為 null 則清空 metadata，回到預設 {} | false |
| expires_at | string | null | 更新到期時間；可指定 ISO8601、null 或 "now" | false |

**補充說明：**

- metadata = object：更新 metadata

- metadata = null：移除 metadata，回到空物件

- expires_at = "now"：立即失效，視同停用

- expires_at = null：移除過期限制

- expires_at = "2026-03-16T00:00:00Z"：指定新的到期時間

#### Response Body

```javascript
{
  "id": "3f90f7e3-7ec5-4c68-8bd1-38f54e90d390",
  "object": "api_key",
  "redacted_value": "sk-xxxxxx...abcd",
  "metadata": {},
  "created_at": "2025-12-16T00:00:00Z",
  "expires_at": "2026-03-16T00:00:00Z"
}
```

**Field Explanation**

| **Field** | **Type** |
| --- | --- |
| id | API Key 的唯一鍵 |
| object | 物件類型，固定為 api_key |
| redacted_value | 遮罩後的 API Key |
| metadata | API Key 的描述資訊 |
| created_at | API Key 建立時間 |
| expires_at | API Key 到期時間 |
