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

建立API Key

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

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

若請求中未提供 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](mailto:alice@example.com)",
"purpose": "UAT"
},
"expires_at": null
}

Field Explanation

FieldTypeDetailRequired
metadataobjectAPI Key 的描述資訊,可用於記錄客戶名稱、聯絡人、用途等false
expires_atstringnullAPI Key 到期時間。可省略、可指定 ISO8601 時間、可設為 null 代表不過期

補充說明:

  • expires_at 省略:系統預設為建立日起 90 天

  • expires_at = null:不設定到期時間

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

Response Body​

{
"id": "3f90f7e3-7ec5-4c68-8bd1-38f54e90d390",
"object": "api_key",
"value": "sk-live-example-only-once",
"redacted_value": "sk-xxxxxx...abcd",
"metadata": {
"customer_name": "ACME Corp",
"contact": "alice@example.com",
"purpose": "UAT"
},
"created_at": "2025-12-16T00:00:00Z",
"expires_at": "2026-03-16T00:00:00Z"
}

Field Explanation

FieldDetail
idAPI Key 的唯一鍵,uuid
object物件類型,固定為 api_key
valueAPI Key 明文,只會在建立當下回傳一次
redacted_value遮罩後的 API Key
metadataAPI Key 的描述資訊
created_atAPI Key 建立時間
expires_atAPI Key 到期時間,null 代表不過期