啟用 API Key¶

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

此 API 同時支援以下操作：

更新 metadata
延長或縮短有效期限
停用 API Key：將 expires_at 設為目前時間
重新啟用 API Key：將 expires_at 設定為未來時間
移除到期限制：將 expires_at 設為 null

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

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
Content-Type	application/json

Query Parameters¶

Field	Type	Note	Required
id	string	uuid	true

Request Payload¶

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

Field Explanation

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

補充說明：

metadata = object：更新 metadata
metadata = null：移除 metadata，回到空物件
expires_at = "now"：立即失效，視同停用
expires_at = null：移除過期限制
expires_at = "2026-03-16T00:00:00Z"：指定新的到期時間

Response Body¶

{
  "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 到期時間