# 取得所有 API Key 列表

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

```bash
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

```json
{
  "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 不存在 |

錯誤格式請參考 [例外狀況處理](https://privstation-docs.apmic.ai/latest/privai-400/例外狀況處理.md)。
