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

建立 API Key

此 API 用於建立一把新的租戶 API Key,僅 Master Key 可呼叫此 API。

  • 建立成功後,系統只會在這一次回應中回傳 API Key 的明文值(value)。之後無法再透過任何 API 重新取得該明文,請立即妥善保存。

  • 新建立的 API Key 以 sk- 開頭。

  • 若請求中未提供 expires_at,系統預設將到期時間設為建立時間起 90 天。

curl -X 'POST' \
'http://127.0.0.1:8000/v1/api-keys' \
-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"
}
}'

Request Headers​

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

Request Payload​

{
"metadata": {
"customer_name": "ACME Corp",
"contact": "alice@example.com",
"purpose": "UAT"
},
"expires_at": null
}

Field Explanation

FieldTypeDetailRequired
metadataobject | nullAPI Key 的描述資訊,為自訂的 key-value 物件,可用於記錄客戶名稱、聯絡人、用途等(欄位名稱僅為範例,無固定欄位)。省略或為 null 時為空物件 {}false
expires_atstring | nullAPI Key 到期時間(ISO8601)。可省略、可指定時間、可設為 null 代表不過期false

補充說明:

  • expires_at 省略:預設為建立時間起 90 天。

  • expires_at = null:不設定到期時間(不會過期)。

  • expires_at = "2026-12-31T00:00:00Z":指定到期時間。建議一律帶上時區(例如 Z 或 +08:00)。

Response Body​

HTTP Status:201 Created

{
"id": "3f90f7e3-7ec5-4c68-8bd1-38f54e90d390",
"object": "api_key",
"redacted_value": "sk-xxxx...xxxx",
"metadata": {
"customer_name": "ACME Corp",
"contact": "alice@example.com",
"purpose": "UAT"
},
"created_at": "2026-10-01T00:00:00Z",
"expires_at": null,
"value": "sk-xxxxxxxx"
}

Field Explanation

FieldDetail
idAPI Key 的唯一鍵,UUID
object物件類型,固定為 api_key
redacted_value遮罩後的 API Key,格式為 sk- 加上隨機字串的前 4 碼與後 4 碼(例如 sk-xxxx...xxxx),僅供辨識用途
metadataAPI Key 的描述資訊
created_atAPI Key 建立時間
expires_atAPI Key 到期時間;null 代表不會過期
valueAPI Key 明文,只會在建立當下回傳一次

除 value 外,其餘欄位即「API Key 物件」,詳見 取得所有 API Key 列表 中的「API Key 物件」一節。

常見錯誤​

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

expires_at 格式錯誤等欄位驗證失敗時會回傳 HTTP 422。錯誤格式請參考 例外狀況處理。