建立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

Key	Value
Request Method	POST
accept	application/json
Authorization	Bearer
Content-Type	application/json

Request Payload

{
"metadata": {
"customer_name": "ACME Corp",
"contact": "[alice@example.com](mailto:alice@example.com)",
"purpose": "UAT"
},
"expires_at": null
}

Field Explanation

Field	Type	Detail	Required
metadata	object	API Key 的描述資訊，可用於記錄客戶名稱、聯絡人、用途等	false
expires_at	string	null	API 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

Field	Detail
id	API Key 的唯一鍵，uuid
object	物件類型，固定為 api_key
value	API Key 明文，只會在建立當下回傳一次
redacted_value	遮罩後的 API Key
metadata	API Key 的描述資訊
created_at	API Key 建立時間
expires_at	API Key 到期時間，null 代表不過期