取得所有 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
| Key | Value |
|---|---|
| Request Method | GET |
| accept | application/json |
| Authorization | Bearer <master-key> |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 10000 | 每次回傳筆數,範圍 1–10000 |
| order | string | desc | 依建立時間排序,asc 或 desc |
| after | string (uuid) | — | 分頁游標,取此 id 之後的資料;不可與 before 同時提供 |
| before | string (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
| Field | Detail |
|---|---|
| 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} 的回應中。
| Field | Detail |
|---|---|
| id | API 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_at | API Key 建立時間 |
| expires_at | API 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 Code | HTTP Status | 情境 |
|---|---|---|
| AUTH_001 | 401 | 缺少 Authorization header |
| AUTH_002 | 403 | Authorization 帶入的不是 Master Key(包含使用租戶 Key 呼叫) |
| VAL_001 | 422 | 同時提供 before 與 after |
| VAL_002 | 404 | before 或 after 所指定的 id 不存在 |
錯誤格式請參考 例外狀況處理。