跳至主要内容
版本:PrivStation 4.0.0
Markdown 原文

更新 / 停用 / 啟用 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​

KeyValue
Request MethodPATCH
acceptapplication/json
AuthorizationBearer <master-key>
Content-Typeapplication/json

Path Parameters​

FieldTypeNoteRequired
idstringuuid,要更新的 API Key idtrue

Request Payload​

以下範例會立即停用 API Key(將到期時間設為過去的時間),並清空 metadata:

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

Field Explanation

FieldTypeNoteRequired
metadataobject | null更新 metadata。帶入物件時會整個取代原本的 metadata(不是合併);為 null 時清空為 {};省略時維持不變false
expires_atstring | 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

FieldDetail
idAPI Key 的唯一鍵,UUID
object物件類型,固定為 api_key
redacted_value遮罩後的 API Key
metadataAPI Key 的描述資訊
created_atAPI Key 建立時間
expires_atAPI Key 到期時間;null 代表不會過期

常見錯誤​

Error CodeHTTP Status情境
AUTH_001401缺少 Authorization header
AUTH_002403Authorization 帶入的不是 Master Key(包含使用租戶 Key 呼叫)
API_KEY_001404指定的 API Key id 不存在

id 不是合法的 UUID、或 expires_at 格式錯誤時,會回傳 HTTP 422。錯誤格式請參考 例外狀況處理。