建立 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
| Key | Value |
|---|---|
| Request Method | POST |
| accept | application/json |
| Authorization | Bearer <master-key> |
| Content-Type | application/json |
Request Payload
{
"metadata": {
"customer_name": "ACME Corp",
"contact": "alice@example.com",
"purpose": "UAT"
},
"expires_at": null
}
Field Explanation
| Field | Type | Detail | Required |
|---|---|---|---|
| metadata | object | null | API Key 的描述資訊,為自訂的 key-value 物件,可用於記錄客戶名稱、聯絡人、用途等(欄位名稱僅為範例,無固定欄位)。省略或為 null 時為空物件 {} | false |
| expires_at | string | null | API 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
| Field | Detail |
|---|---|
| id | API Key 的唯一鍵,UUID |
| object | 物件類型,固定為 api_key |
| redacted_value | 遮罩後的 API Key,格式為 sk- 加上隨機字串的前 4 碼與後 4 碼(例如 sk-xxxx...xxxx),僅供辨識用途 |
| metadata | API Key 的描述資訊 |
| created_at | API Key 建立時間 |
| expires_at | API Key 到期時間;null 代表不會過期 |
| value | API Key 明文,只會在建立當下回傳一次 |
除 value 外,其餘欄位即「API Key 物件」,詳見 取得所有 API Key 列表 中的「API Key 物件」一節。
常見錯誤
| Error Code | HTTP Status | 情境 |
|---|---|---|
| AUTH_001 | 401 | 缺少 Authorization header |
| AUTH_002 | 403 | Authorization 帶入的不是 Master Key(包含使用租戶 Key 呼叫) |
expires_at 格式錯誤等欄位驗證失敗時會回傳 HTTP 422。錯誤格式請參考 例外狀況處理。