# 建立 API Key

此 API 用於建立一把新的租戶 API Key，僅 **Master Key** 可呼叫此 API。

- 建立成功後，系統只會在這一次回應中回傳 API Key 的明文值（`value`）。之後無法再透過任何 API 重新取得該明文，請立即妥善保存。

- 新建立的 API Key 以 `sk-` 開頭。

- 若請求中未提供 `expires_at`，系統預設將到期時間設為建立時間起 90 天。

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

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

```json
{
  "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 列表](https://privstation-docs.apmic.ai/latest/privai-400/取得所有-api-key-列表.md) 中的「API Key 物件」一節。

#### 常見錯誤

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| AUTH_001 | 401 | 缺少 `Authorization` header |
| AUTH_002 | 403 | `Authorization` 帶入的不是 Master Key（包含使用租戶 Key 呼叫） |

`expires_at` 格式錯誤等欄位驗證失敗時會回傳 HTTP 422。錯誤格式請參考 [例外狀況處理](https://privstation-docs.apmic.ai/latest/privai-400/例外狀況處理.md)。
