更新 / 停用 / 啟用 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 明文。
省略 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。
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:
{
"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 列表 中的「API Key 物件」一節)。
{
"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。錯誤格式請參考 例外狀況處理。