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

取得所有 API Key 列表

此 API 用於列出目前系統中所有已建立的 API Key,僅 Master Key 可呼叫此 API。
回傳資料不包含 API Key 明文,只會提供遮罩後的值(redacted_value)、描述資訊(metadata)、建立時間與到期時間等欄位,方便管理者辨識、管理與維護。此 API 支援游標式分頁,規則詳見「分頁策略 & 文件解析模式優化策略 (PDF)」章節。

curl -X 'GET' \
'http://127.0.0.1:8000/v1/api-keys?limit=100&order=desc' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <master-key>'

Request Headers​

KeyValue
Request MethodGET
acceptapplication/json
AuthorizationBearer <master-key>

Query Parameters​

ParameterTypeDefaultDescription
limitinteger10000每次回傳筆數,範圍 1–10000
orderstringdesc依建立時間排序,asc 或 desc
afterstring (uuid)—分頁游標,取此 id 之後的資料;不可與 before 同時提供
beforestring (uuid)—分頁游標,取此 id 之前的資料;不可與 after 同時提供

Response Body​

{
"object": "list",
"data": [
{
"id": "98ab1f23-6d89-4b55-a1b7-96b8fd3f4e11",
"object": "api_key",
"redacted_value": "sk-xxxx...wxyz",
"metadata": {
"customer_name": "Beta Inc.",
"contact": "bob@example.com",
"purpose": "Production"
},
"created_at": "2026-09-20T08:30:00Z",
"expires_at": null
},
{
"id": "3f90f7e3-7ec5-4c68-8bd1-38f54e90d390",
"object": "api_key",
"redacted_value": "sk-xxxx...abcd",
"metadata": {
"customer_name": "ACME Corp",
"contact": "alice@example.com",
"purpose": "UAT"
},
"created_at": "2026-06-16T00:00:00Z",
"expires_at": "2026-12-16T00:00:00Z"
}
],
"first_id": "98ab1f23-6d89-4b55-a1b7-96b8fd3f4e11",
"last_id": "3f90f7e3-7ec5-4c68-8bd1-38f54e90d390",
"has_more": false
}

Field Explanation

FieldDetail
object(與 OpenAI 相容而保留),固定為 list
data[]API Key 列表,每筆為一個「API Key 物件」,請參考下方「API Key 物件」一節
first_id本頁第一筆 API Key 的 id;無資料時為 null
last_id本頁最後一筆 API Key 的 id;無資料時為 null
has_more是否還有更多 API Key

API Key 物件​

API Key 物件出現在 GET /v1/api-keys 的 data[] 與 PATCH /v1/api-keys/{id} 的回應中。

FieldDetail
idAPI Key 的唯一鍵,UUID
object物件類型,固定為 api_key
redacted_value遮罩後的 API Key 顯示值,格式為 sk- 加上隨機字串的前 4 碼與後 4 碼(例如 sk-xxxx...xxxx),僅供辨識用途
metadata自訂的 key-value 物件,用於記錄與此 API Key 相關的描述資訊(例如 customer name、contact、purpose,僅為範例),無固定欄位
created_atAPI Key 建立時間
expires_atAPI Key 到期時間;null 代表不設定到期時間(不會過期)

補充說明:

  • API Key 的明文(value)只會在 POST /v1/api-keys 建立當下的回應中出現一次。之後任何 API(包含 GET /v1/api-keys、PATCH /v1/api-keys/{id})都只會回傳 redacted_value,無法再取得明文,因此 API Key 物件不含 value 欄位。

  • 列表會包含已過期(已停用)的 API Key,可依 expires_at 判斷目前是否有效。

常見錯誤​

Error CodeHTTP Status情境
AUTH_001401缺少 Authorization header
AUTH_002403Authorization 帶入的不是 Master Key(包含使用租戶 Key 呼叫)
VAL_001422同時提供 before 與 after
VAL_002404before 或 after 所指定的 id 不存在

錯誤格式請參考 例外狀況處理。